Document how to use blob store functions without authentication #76

Author: andrie

R/AzureBlob.R

@@ -4,13 +4,17 @@
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
+#' @param azureActiveContext Either an `azureActiveContext` object or `NULL`. The blob store functions support two modes of connecting to the Azure API: authenticate using Active Directory or providing your own storage key. If this value is `NULL`, you must provide the `storageKey`.
 #'
 #' @param maxresults Optional. Specifies the maximum number of blobs to return, including all BlobPrefix elements. If the request does not specify maxresults or specifies a value greater than 5,000, the server will return up to 5,000 items.  Setting `maxresults` to a value less than or equal to zero results in error response code 400 (Bad Request).
 #' @param prefix Optional. Filters the results to return only blobs whose names begin with the specified prefix.
 #' @param delimiter Optional. When the request includes this parameter, the operation returns a BlobPrefix element in the response body that acts as a placeholder for all blobs whose names begin with the same substring up to the appearance of the delimiter character. The delimiter may be a single character or a string.
 #' @param marker Optional. A string value that identifies the portion of the list to be returned with the next list operation. The operation returns a marker value within the response body if the list returned was not complete. The marker value may then be used in a subsequent call to request the next set of list items.  The marker value is opaque to the client.
 #'
 #' @return Returns a data frame. This data frame has an attribute called `marker` that can be used with the `marker` argument to return the next set of values.
+#'
+#' @template blob_no_authentication
+#' @references https://docs.microsoft.com/en-us/rest/api/storageservices/list-blobs
 #' @family Blob store functions
 #' @export
 azureListStorageBlobs <- function(azureActiveContext, storageAccount, storageKey,
@@ -92,13 +96,15 @@ azureListStorageBlobs <- function(azureActiveContext, storageAccount, storageKey
 
 #' List blob blobs in a storage account directory.
 #'
+#' @inheritParams azureListStorageBlobs
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
-
+#'
 #' @param directory Blob store directory to list for content
 #' @param recursive If TRUE, list blob store directories recursively
 #'
+#' @template blob_no_authentication
 #' @family Blob store functions
 #' @export
 azureBlobLS <- function(azureActiveContext, directory, recursive = FALSE,
@@ -181,13 +187,15 @@ azureBlobLS <- function(azureActiveContext, directory, recursive = FALSE,
 
 #' Get contents from a specifed storage blob.
 #'
+#' @inheritParams azureListStorageBlobs
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
 #' @inheritParams azureBlobLS
-
+#'
 #' @param type String, either "text" or "raw". Passed to [httr::content()]
 #'
+#' @template blob_no_authentication
 #' @family Blob store functions
 #' @export
 
@@ -257,6 +265,7 @@ azureGetBlob <- function(azureActiveContext, blob, directory, type = "text",
 
 #' Write contents to a specifed storage blob.
 #'
+#' @inheritParams azureListStorageBlobs
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
@@ -265,6 +274,7 @@ azureGetBlob <- function(azureActiveContext, blob, directory, type = "text",
 #' @param contents - Object or value to store
 #' @param file - Local filename to store in Azure blob
 #'
+#' @template blob_no_authentication
 #' @family Blob store functions
 #' @export
 azurePutBlob <- function(azureActiveContext, blob, contents = "", file = "",
@@ -337,11 +347,13 @@ azurePutBlob <- function(azureActiveContext, blob, contents = "", file = "",
 
 #' Find file in a storage account directory.
 #'
+#' @inheritParams azureListStorageBlobs
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
 #' @inheritParams azurePutBlob
 #'
+#' @template blob_no_authentication
 #' @family Blob store functions
 #' @export
 azureBlobFind <- function(azureActiveContext, file, storageAccount, storageKey,
@@ -383,12 +395,14 @@ azureBlobFind <- function(azureActiveContext, file, storageAccount, storageKey,
 
 #' Azure blob change current directory.
 #'
+#' @inheritParams azureListStorageBlobs
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
 #' @inheritParams azureBlobLS
 #' @inheritParams azurePutBlob
 #'
+#' @template blob_no_authentication
 #' @family Blob store functions
 #' @export
 azureBlobCD <- function(azureActiveContext, directory, container, file,
@@ -430,7 +444,7 @@ azureBlobCD <- function(azureActiveContext, directory, container, file,
   assert_that(is_storage_key(storageKey))
 
   if (directory == "../" || directory == "..") {
-    # Basic attempt azToken relative paths
+    # Basic attempt at relative paths
     directory <- gsub("/[a-zA-Z0-9]*$", "", azureActiveContext$directory)
   }
 
@@ -458,11 +472,13 @@ azureBlobCD <- function(azureActiveContext, directory, container, file,
 
 #' Delete a specifed storage blob.
 #'
+#' @inheritParams azureListStorageBlobs
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureSAGetKey
 #' @inheritParams azureBlobLS
 #'
+#' @template blob_no_authentication
 #' @family Blob store functions
 #' @export
 

R/AzureContextObject.R

@@ -38,10 +38,10 @@ createAzureContext <- function(tenantID, clientID, authKey, configFile){
 #'
 #' Updates the value of an `azureActiveContext` object, created by [createAzureContext()]
 #'
-#' @param azureActiveContext A container used for caching variables used by `AzureSMR`
-#' @param tenantID The Tenant ID provided during creation of the Active Directory application / service principal
-#' @param clientID The Client ID provided during creation of the Active Directory application / service principal
-#' @param authKey The Authentication Key provided during creation of the Active Directory application / service principal
+#' @param azureActiveContext A container used for caching variables used by `AzureSMR`, created by [createAzureContext()]
+#' @param tenantID The tenant ID provided during creation of the Active Directory application / service principal
+#' @param clientID The client ID provided during creation of the Active Directory application / service principal
+#' @param authKey The authentication key provided during creation of the Active Directory application / service principal
 #' @param subscriptionID Subscription ID.  This is obtained automatically by [azureAuthenticate()] when only a single subscriptionID is available via Active Directory
 #' @param resourceGroup Name of the resource group
 #' @param vmName Name of the virtual machine

R/AzureCost.R

@@ -10,9 +10,7 @@
 #' 
 #' @inheritParams setAzureContext
 #' 
-#' @param instance Instance name that one would like to check expe
-#' nse. It is by default empty, which returns data consumption for 
-#' all instances under subscription.
+#' @param instance Instance name that one would like to check expense. It is by default empty, which returns data consumption for all instances under subscription.
 #' 
 #' @param timeStart Start time.
 #' @param timeEnd End time.
@@ -228,6 +226,8 @@ azureDataConsumption <- function(azureActiveContext,
 
 #' Get pricing details of resources under a subscription.
 #' 
+#' The pricing rates function wraps API calls to Azure RateCard and currently the API supports only the Pay-As-You-Go offer scheme. 
+#'
 #' @inheritParams setAzureContext
 #' 
 #' @param currency Currency in which price rating is measured.
@@ -236,8 +236,6 @@ azureDataConsumption <- function(azureActiveContext,
 #' 
 #' @param region region information about the subscription.
 #' 
-#' @note The pricing rates function wraps API calls to Azure RateCard and currently the API supports only the Pay-As-You-Go offer scheme. 
-#' 
 #' @family Cost functions
 #' @export
 azurePricingRates <- function(azureActiveContext,
@@ -313,8 +311,7 @@ azurePricingRates <- function(azureActiveContext,
 #' @inheritParams azureDataConsumption
 #' @inheritParams azurePricingRates
 #' 
-#' @return Total cost measured in the given currency of the specified Azure 
-#' instance in the period.
+#' @return Total cost measured in the given currency of the specified Azure instance in the period.
 #' 
 #' @family Cost functions
 #' @export

man-roxygen/blob_no_authentication.R

@@ -0,0 +1,2 @@
+#' @section Using blob store functions without authentication:
+#' The blob store functions support two modes of connecting to the Azure API:authenticate using Active Directory or providing your own storage key. If this value is `NULL`, you must provide the `storageKey` .