fix: include all possible parameters for this method

R/download_tableau_data.R

@@ -6,13 +6,36 @@
 #' @param view_id The ID of the view to download.
 #' @param path_to_save The directory to write the data Excel file to.
 #' @param api_version The API version to use (default: 3.8).
+#' @param filters A named list of filters to apply to the view data. The names should be the field names, and the values should be the filter values.
+#' @param max_age The maximum number of minutes view data will be cached before being refreshed (optional).
 #'
 #' @return NULL
 #'
-#' @export
+#' @details
+#' This function uses the Tableau REST API to download data from a specified view in Excel format.
+#' It constructs the appropriate URL, applies any specified filters, and saves the data to the specified path.
+#'
+#' For more information on the Tableau REST API, see the official documentation for this method:
+#' \url{https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_view_data}
 #'
+#' @examples
+#' \dontrun{
+#' tableau <- list(
+#'   base_url = "https://your-tableau-server.com/",
+#'   token = "your-auth-token",
+#'   user_id = "your-user-id",
+#'   site_id = "your-site-id"
+#' )
+#' view_id <- "your-view-id"
+#' path_to_save <- "path/to/save/"
+#' filters <- list("Region" = "North America", "Category" = "Technology")
+#' max_age <- 10
+#' download_tableau_data(tableau, view_id, path_to_save, filters = filters, max_age = max_age)
+#' }
+#'
+#' @export
 #' @family Tableau REST API
-download_tableau_data <- function(tableau, view_id, path_to_save, api_version = 3.8) {
+download_tableau_data <- function(tableau, view_id, path_to_save, api_version = 3.8, filters = NULL, max_age = NULL) {
   base_url <- tableau$base_url
   token <- tableau$token
   site_id <- tableau$site_id
@@ -23,8 +46,25 @@ download_tableau_data <- function(tableau, view_id, path_to_save, api_version =
     site_id, "/views/", view_id, "/data"
   )
 
-  # Construct the URL
-  url <- paste0(base_url, "?format=csv")
+  # Construct the URL with filters and maxAge
+  url <- base_url
+  params <- list()
+
+  if (!is.null(filters)) {
+    # URL encode filter names and values
+    names(filters) <- sapply(names(filters), utils::URLencode, reserved = TRUE)
+    filters <- sapply(filters, utils::URLencode, reserved = TRUE)
+    filter_params <- paste0("vf_", names(filters), "=", filters, collapse = "&")
+    params <- c(params, filter_params)
+  }
+
+  if (!is.null(max_age)) {
+    params <- c(params, paste0("maxAge=", max_age))
+  }
+
+  if (length(params) > 0) {
+    url <- paste0(url, "?", paste(params, collapse = "&"))
+  }
 
   # Download the data as CSV
   httr::GET(