feat: add get_log(job)

NAMESPACE

@@ -81,6 +81,7 @@ export(get_group_permission)
 export(get_groups)
 export(get_image)
 export(get_job)
+export(get_job_log)
 export(get_jobs)
 export(get_my_permission)
 export(get_oauth_content_credentials)

NEWS.md

@@ -1,5 +1,15 @@
 # connectapi (development version)
 
+## New features
+
+- New `get_job_log()` function which lets you get the log for a given job.
+  (#341)
+
+## Newly deprecated
+
+- `get_job()` (singular) is now deprecated, its functionality taken care of by
+  other functions, including `get_job_log()`.
+
 # connectapi 0.5.0
 
 ## Breaking changes

R/content.R

@@ -660,6 +660,13 @@ content_ensure <- function(
 #' @note
 #' 1. On Connect instances earlier than 2022.10.0, these columns will contain `NA` values.
 #'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' item <- content_item(client, "951bf3ad-82d0-4bca-bba8-9b27e35c49fa")
+#' jobs <- get_jobs(item)
+#' }
+#'
 #' @family job functions
 #' @family content functions
 #' @export
@@ -682,7 +689,7 @@ get_jobs <- function(content) {
 #' @family content functions
 #' @export
 get_job <- function(content, key) {
-  warn_experimental("get_job")
+  lifecycle::deprecate_warn("0.6", "get_job()", "get_job_log()")
   scoped_experimental_silence()
   validate_R6_class(content, "Content")
 
@@ -718,6 +725,13 @@ get_job <- function(content, key) {
 #' Note that `app_id`, `app_guid`, `job_id`, and `result` are `NA` if the
 #' request returns an error.
 #'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' item <- content_item(client, "951bf3ad-82d0-4bca-bba8-9b27e35c49fa")
+#' result <- terminate_jobs(item)
+#' }
+#'
 #' @family job functions
 #' @family content functions
 #' @export
@@ -747,6 +761,49 @@ terminate_jobs <- function(content, keys = NULL) {
   res_df
 }
 
+#' Get Job Log
+#'
+#' Get the log output for a job. Requires Connect 2022.10.0 or newer.
+#'
+#' @param content A Content object, as returned by `content_item()`
+#' @param key A job key, which you can find using `get_jobs()`
+#' @param max_log_lines Optional. An integer indicating the maximum number of
+#' log lines to return. If `NULL` (default), Connect returns a maximum of 5000
+#' lines.
+#'
+#' @return A data frame with the requested log. Each row represents an entry.
+#'
+#' - `source`: `stdout` or `stderr`
+#' - `timestamp`: The time of the entry.
+#' - `data`: The logged text.
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#' item <- content_item(client, "951bf3ad-82d0-4bca-bba8-9b27e35c49fa")
+#' jobs <- get_jobs(item)
+#' key <- jobs$key[1]
+#' log <- get_job_log(item, key)
+#' }
+#'
+#'
+#' @family job functions
+#' @family content functions
+#' @export
+get_job_log <- function(content, key, max_log_lines = NULL) {
+  validate_R6_class(content, "Content")
+
+  error_if_less_than(content$connect$version, "2022.10.0")
+
+  query <- list(maxLogLines = max_log_lines)
+  print(query)
+  res <- content$connect$GET(
+    v1_url("content", content$content$guid, "jobs", key, "log"),
+    query = query
+  )
+  parse_connectapi_typed(res$entries, connectapi_ptypes$job_log)
+}
+
 #' Set RunAs User
 #'
 #' Set the `RunAs` user for a piece of content.

R/parse.R

@@ -169,8 +169,8 @@ parse_connect_rfc3339 <- function(x) {
     # Times with and without offsets require different formats.
     format_string <- ifelse(
       grepl("Z$", .x),
-      "%Y-%m-%dT%H:%M:%SZ",
-      "%Y-%m-%dT%H:%M:%S%z"
+      "%Y-%m-%dT%H:%M:%OSZ",
+      "%Y-%m-%dT%H:%M:%OS%z"
     )
     as.POSIXct(strptime(.x, format = format_string, tz = "UTC"))
   })

R/ptype.R

@@ -238,5 +238,10 @@ connectapi_ptypes <- list(
     content_guid = NA_character_,
     path = NA_character_,
     created_time = NA_datetime_
+  ),
+  job_log = tibble::tibble(
+    source = NA_character_,
+    timestamp = NA_datetime_,
+    data = NA_character_
   )
 )