add examples

R/add_methods.R

@@ -15,7 +15,7 @@
 #' ```
 #' @section Arguments:
 #' - `name`: The name of the storage account.
-#' - `location`: The location/region in which to create the account.
+#' - `location`: The location/region in which to create the account. Defaults to the resource group location.
 #' - `kind`: The type of account, either `"StorageV2"` (the default), `"FileStorage"` or `"BlobStorage"`.
 #' - `replication`: The replication strategy for the account. The default is locally-redundant storage (LRS).
 #' - `access_tier`: The access tier, either `"hot"` or `"cool"`, for blobs.
@@ -39,6 +39,23 @@
 #' @seealso
 #' [get_storage_account], [delete_storage_account], [az_storage],
 #' [Azure Storage Provider API reference](https://docs.microsoft.com/en-us/rest/api/storagerp/)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' rg <- AzureRMR::az_rm(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")$
+#'     get_subscription("subscription_id")$
+#'     get_resource_group("rgname")
+#'
+#' # create a new storage account
+#' rg$create_storage_account("mystorage", kind="StorageV2")
+#'
+#' # create a blob storage account in a different region
+#' rg$create_storage_account("myblobstorage",
+#'     location="australiasoutheast",
+#'     kind="BlobStorage")
+#'
+#' }
 NULL
 
 
@@ -69,6 +86,18 @@ NULL
 #' @seealso
 #' [create_storage_account], [delete_storage_account], [az_storage],
 #' [Azure Storage Provider API reference](https://docs.microsoft.com/en-us/rest/api/storagerp/)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' rg <- AzureRMR::az_rm(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")$
+#'     get_subscription("subscription_id")$
+#'     get_resource_group("rgname")
+#'
+#' # get a storage account
+#' rg$get_storage_account("mystorage")
+#'
+#' }
 NULL
 
 
@@ -95,6 +124,18 @@ NULL
 #' @seealso
 #' [create_storage_account], [get_storage_account], [az_storage],
 #' [Azure Storage Provider API reference](https://docs.microsoft.com/en-us/rest/api/storagerp/)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' rg <- AzureRMR::az_rm(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")$
+#'     get_subscription("subscription_id")$
+#'     get_resource_group("rgname")
+#'
+#' # delete a storage account
+#' rg$delete_storage_account("mystorage")
+#'
+#' }
 NULL
 
 

R/blob_client_funcs.R

@@ -22,6 +22,25 @@
 #'
 #' @seealso [storage_endpoint], [az_storage]
 #'
+#' @examples
+#' \dontrun{
+#'
+#' endp <- blob_endpoint("https://mystorage.blob.core.windows.net/", key="access_key")
+#'
+#' # list containers
+#' list_blob_containers(endp)
+#'
+#' # get, create, and delete a container
+#' blob_container(endp, "mycontainer")
+#' create_blob_container(endp, "newcontainer")
+#' delete_blob_container(endp, "newcontainer")
+#'
+#' # alternative way to do the same
+#' blob_container("https://mystorage.blob.core.windows.net/mycontainer", key="access_key")
+#' create_blob_container("https://mystorage.blob.core.windows.net/newcontainer", key="access_key")
+#' delete_blob_container("https://mystorage.blob.core.windows.net/newcontainer", key="access_key")
+#'
+#' }
 #' @rdname blob_container
 #' @export
 blob_container <- function(endpoint, ...)
@@ -191,6 +210,19 @@ delete_blob_container.blob_endpoint <- function(endpoint, name, confirm=TRUE, le
 #' @seealso
 #' [blob_container], [az_storage]
 #'
+#' @examples
+#' \dontrun{
+#'
+#' cont <- blob_container("https://mystorage.blob.core.windows.net/mycontainer", key="access_key")
+#'
+#' list_blobs(cont)
+#'
+#' upload_blob(cont, "~/bigfile.zip", dest="bigfile.zip")
+#' download_blob(cont, "bigfile.zip", dest="~/bigfile_downloaded.zip")
+#'
+#' delete_blob(cont, "bigfile.zip")
+#'
+#' }
 #' @rdname blob
 #' @export
 list_blobs <- function(container, info=c("partial", "name", "all"),

R/client.R

@@ -16,6 +16,16 @@
 #' @seealso
 #' [az_storage], [file_share], [create_file_share], [blob_container], [create_blob_container]
 #'
+#' @examples
+#' \dontrun{
+#'
+#' # obtaining an endpoint from the storage account resource object
+#' endp <- stor$get_blob_endpoint()
+#'
+#' # creating an endpoint standalone
+#' endp <- blob_endpoint("https://mystorage.blob.core.windows.net/", key="access_key")
+#'
+#' }
 #' @aliases endpoint blob_endpoint file_endpoint queue_endpoint table_endpoint
 #' @export
 storage_endpoint <- function(endpoint, key=NULL, sas=NULL, api_version=getOption("azure_storage_api_version"))
@@ -89,6 +99,15 @@ print.storage_endpoint <- function(x, ...)
 #' @seealso
 #' [download_azure_file], [download_blob], [az_storage]
 #'
+#' @examples
+#' \dontrun{
+#'
+#' # authenticated download with an access key
+#' download_from_url("https://mystorage.blob.core.windows.net/mycontainer/bigfile.zip",
+#'                   "~/bigfile.zip",
+#'                   key="access_key")
+#'
+#' }
 #' @rdname file_transfer
 #' @export
 download_from_url <- function(src, dest, key=NULL, sas=NULL, ..., overwrite=FALSE)

R/file_client_funcs.R

@@ -20,6 +20,25 @@
 #'
 #' @seealso [storage_endpoint], [az_storage]
 #'
+#' @examples
+#' \dontrun{
+#'
+#' endp <- file_endpoint("https://mystorage.file.core.windows.net/", key="access_key")
+#'
+#' # list file shares
+#' list_file_shares(endp)
+#'
+#' # get, create, and delete a file share
+#' file_share(endp, "myshare")
+#' create_file_share(endp, "newshare")
+#' delete_file_share(endp, "newshare")
+#'
+#' # alternative way to do the same
+#' file_share("https://mystorage.blob.core.windows.net/myshare", key="access_key")
+#' create_file_share("https://mystorage.blob.core.windows.net/newshare", key="access_key")
+#' delete_file_share("https://mystorage.blob.core.windows.net/newshare", key="access_key")
+#'
+#' }
 #' @rdname file_share
 #' @export
 file_share <- function(endpoint, ...)
@@ -180,6 +199,22 @@ delete_file_share.file_endpoint <- function(endpoint, name, confirm=TRUE, ...)
 #' @seealso
 #' [file_share], [az_storage]
 #'
+#' @examples
+#' \dontrun{
+#'
+#' share <- file_share("https://mystorage.file.core.windows.net/myshare", key="access_key")
+#'
+#' list_azure_files(share, "/")
+#'
+#' create_azure_dir(share, "/newdir")
+#'
+#' upload_azure_file(share, "~/bigfile.zip", dest="/newdir/bigfile.zip")
+#' download_azure_file(share, "/newdir/bigfile.zip", dest="~/bigfile_downloaded.zip")
+#'
+#' delete_azure_file(share, "/newdir/bigfile.zip")
+#' delete_azure_dir(share, "/newdir")
+#'
+#' }
 #' @rdname file
 #' @export
 list_azure_files <- function(share, dir, info=c("all", "name"),

R/storage.R

@@ -10,8 +10,6 @@
 #' - `get_account_sas(...)`: Return an account shared access signature (SAS). See 'Shared access signatures' for more details.
 #' - `get_blob_endpoint(key, sas)`: Return the account's blob storage endpoint, along with an access key and/or a SAS. See 'Endpoints' for more details
 #' - `get_file_endpoint(key, sas)`: Return the account's file storage endpoint.
-#' - `get_queue_endpoint(key, sas)`: Return the account's queue storage endpoint.
-#' - `get_table_endpoint(key, sas)`: Return the account's table storage endpoint.
 #' - `regen_key(key)`: Regenerates (creates a new value for) an access key. The argument `key` can be 1 or 2.
 #'
 #' @section Initialization:
@@ -44,6 +42,28 @@
 #' [create_storage_account], [get_storage_account], [delete_storage_account], [Date], [POSIXt],
 #' [Azure Storage Provider API reference](https://docs.microsoft.com/en-us/rest/api/storagerp/),
 #' [Azure Storage Services API reference](https://docs.microsoft.com/en-us/rest/api/storageservices/)
+#'
+#' @examples
+#' \dontrun{
+#'
+#' # recommended way of retrieving a resource: via a resource group object
+#' stor <- resgroup$get_storage_account("mystorage")
+#'
+#' # list account access keys
+#' stor$list_keys()
+#'
+#' # regenerate a key
+#' stor$regen_key(1)
+#'
+#' # generate a shared access signature for blob storage, expiring in 7 days time
+#' today <- Sys.time()
+#' stor$get_account_sas(expiry=today + 7*24*60*60, services="b", permissions="rw")
+#'
+#' # storage endpoints
+#' stor$get_blob_endpoint()
+#' stor$get_file_endpoint()
+#'
+#' }
 #' @export
 az_storage <- R6::R6Class("az_storage", inherit=AzureRMR::az_resource,
 

man/az_storage.Rd

@@ -20,8 +20,6 @@ The following methods are available, in addition to those provided by the \link[
 \item \code{get_account_sas(...)}: Return an account shared access signature (SAS). See 'Shared access signatures' for more details.
 \item \code{get_blob_endpoint(key, sas)}: Return the account's blob storage endpoint, along with an access key and/or a SAS. See 'Endpoints' for more details
 \item \code{get_file_endpoint(key, sas)}: Return the account's file storage endpoint.
-\item \code{get_queue_endpoint(key, sas)}: Return the account's queue storage endpoint.
-\item \code{get_table_endpoint(key, sas)}: Return the account's table storage endpoint.
 \item \code{regen_key(key)}: Regenerates (creates a new value for) an access key. The argument \code{key} can be 1 or 2.
 }
 }
@@ -59,6 +57,28 @@ To create a storage endpoint independently of Resource Manager (for example if y
 If a storage endpoint is created without an access key and SAS, only public (anonymous) access is possible.
 }
 
+\examples{
+\dontrun{
+
+# recommended way of retrieving a resource: via a resource group object
+stor <- resgroup$get_storage_account("mystorage")
+
+# list account access keys
+stor$list_keys()
+
+# regenerate a key
+stor$regen_key(1)
+
+# generate a shared access signature for blob storage, expiring in 7 days time
+today <- Sys.time()
+stor$get_account_sas(expiry=today + 7*24*60*60, services="b", permissions="rw")
+
+# storage endpoints
+stor$get_blob_endpoint()
+stor$get_file_endpoint()
+
+}
+}
 \seealso{
 \link{blob_endpoint}, \link{file_endpoint},
 \link{create_storage_account}, \link{get_storage_account}, \link{delete_storage_account}, \link{Date}, \link{POSIXt},

man/blob.Rd

@@ -44,6 +44,20 @@ For \code{list_blobs}, details on the blobs in the container.
 \description{
 Upload, download, or delete a blob; list blobs in a container.
 }
+\examples{
+\dontrun{
+
+cont <- blob_container("https://mystorage.blob.core.windows.net/mycontainer", key="access_key")
+
+list_blobs(cont)
+
+upload_blob(cont, "~/bigfile.zip", dest="bigfile.zip")
+download_blob(cont, "bigfile.zip", dest="~/bigfile_downloaded.zip")
+
+delete_blob(cont, "bigfile.zip")
+
+}
+}
 \seealso{
 \link{blob_container}, \link{az_storage}
 }

man/blob_container.Rd

@@ -84,6 +84,26 @@ Get, list, create, or delete blob containers.
 \details{
 You can call these functions in a couple of ways: by passing the full URL of the share, or by passing the endpoint object and the name of the container as a string.
 }
+\examples{
+\dontrun{
+
+endp <- blob_endpoint("https://mystorage.blob.core.windows.net/", key="access_key")
+
+# list containers
+list_blob_containers(endp)
+
+# get, create, and delete a container
+blob_container(endp, "mycontainer")
+create_blob_container(endp, "newcontainer")
+delete_blob_container(endp, "newcontainer")
+
+# alternative way to do the same
+blob_container("https://mystorage.blob.core.windows.net/mycontainer", key="access_key")
+create_blob_container("https://mystorage.blob.core.windows.net/newcontainer", key="access_key")
+delete_blob_container("https://mystorage.blob.core.windows.net/newcontainer", key="access_key")
+
+}
+}
 \seealso{
 \link{storage_endpoint}, \link{az_storage}
 }

man/create_storage_account.Rd

@@ -17,7 +17,7 @@ Method for the \link[AzureRMR:az_resource_group]{AzureRMR::az_resource_group} cl
 
 \itemize{
 \item \code{name}: The name of the storage account.
-\item \code{location}: The location/region in which to create the account.
+\item \code{location}: The location/region in which to create the account. Defaults to the resource group location.
 \item \code{kind}: The type of account, either \code{"StorageV2"} (the default), \code{"FileStorage"} or \code{"BlobStorage"}.
 \item \code{replication}: The replication strategy for the account. The default is locally-redundant storage (LRS).
 \item \code{access_tier}: The access tier, either \code{"hot"} or \code{"cool"}, for blobs.
@@ -46,6 +46,23 @@ Accounts created with \code{kind = "BlobStorage"} can only host blob storage, wh
 An object of class \code{az_storage} representing the created storage account.
 }
 
+\examples{
+\dontrun{
+
+rg <- AzureRMR::az_rm(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")$
+    get_subscription("subscription_id")$
+    get_resource_group("rgname")
+
+# create a new storage account
+rg$create_storage_account("mystorage", kind="StorageV2")
+
+# create a blob storage account in a different region
+rg$create_storage_account("myblobstorage",
+    location="australiasoutheast",
+    kind="BlobStorage")
+
+}
+}
 \seealso{
 \link{get_storage_account}, \link{delete_storage_account}, \link{az_storage},
 \href{https://docs.microsoft.com/en-us/rest/api/storagerp/}{Azure Storage Provider API reference}

man/delete_storage_account.Rd

@@ -25,6 +25,18 @@ Method for the \link[AzureRMR:az_resource_group]{AzureRMR::az_resource_group} cl
 NULL on successful deletion.
 }
 
+\examples{
+\dontrun{
+
+rg <- AzureRMR::az_rm(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")$
+    get_subscription("subscription_id")$
+    get_resource_group("rgname")
+
+# delete a storage account
+rg$delete_storage_account("mystorage")
+
+}
+}
 \seealso{
 \link{create_storage_account}, \link{get_storage_account}, \link{az_storage},
 \href{https://docs.microsoft.com/en-us/rest/api/storagerp/}{Azure Storage Provider API reference}

man/file.Rd

@@ -44,6 +44,23 @@ For \code{list_azure_files}, if \code{info="name"}, a vector of file/directory n
 \description{
 Upload, download, or delete a file; list files in a directory; create or delete directories.
 }
+\examples{
+\dontrun{
+
+share <- file_share("https://mystorage.file.core.windows.net/myshare", key="access_key")
+
+list_azure_files(share, "/")
+
+create_azure_dir(share, "/newdir")
+
+upload_azure_file(share, "~/bigfile.zip", dest="/newdir/bigfile.zip")
+download_azure_file(share, "/newdir/bigfile.zip", dest="~/bigfile_downloaded.zip")
+
+delete_azure_file(share, "/newdir/bigfile.zip")
+delete_azure_dir(share, "/newdir")
+
+}
+}
 \seealso{
 \link{file_share}, \link{az_storage}
 }

man/file_share.Rd

@@ -76,6 +76,26 @@ Get, list, create, or delete file shares.
 \details{
 You can call these functions in a couple of ways: by passing the full URL of the share, or by passing the endpoint object and the name of the share as a string.
 }
+\examples{
+\dontrun{
+
+endp <- file_endpoint("https://mystorage.file.core.windows.net/", key="access_key")
+
+# list file shares
+list_file_shares(endp)
+
+# get, create, and delete a file share
+file_share(endp, "myshare")
+create_file_share(endp, "newshare")
+delete_file_share(endp, "newshare")
+
+# alternative way to do the same
+file_share("https://mystorage.blob.core.windows.net/myshare", key="access_key")
+create_file_share("https://mystorage.blob.core.windows.net/newshare", key="access_key")
+delete_file_share("https://mystorage.blob.core.windows.net/newshare", key="access_key")
+
+}
+}
 \seealso{
 \link{storage_endpoint}, \link{az_storage}
 }

man/file_transfer.Rd

@@ -27,6 +27,16 @@ These functions allow you to transfer files to and from a storage account, given
 
 You can provide a SAS either as part of the URL itself, or in the \code{sas} argument.
 }
+\examples{
+\dontrun{
+
+# authenticated download with an access key
+download_from_url("https://mystorage.blob.core.windows.net/mycontainer/bigfile.zip",
+                  "~/bigfile.zip",
+                  key="access_key")
+
+}
+}
 \seealso{
 \link{download_azure_file}, \link{download_blob}, \link{az_storage}
 }

man/get_storage_account.Rd

@@ -32,6 +32,18 @@ For \code{get_storage_account()}, an object of class \code{az_storage} represent
 For \code{list_storage_accounts()}, a list of such objects.
 }
 
+\examples{
+\dontrun{
+
+rg <- AzureRMR::az_rm(tenant="myaadtenant.onmicrosoft.com", app="app_id", password="password")$
+    get_subscription("subscription_id")$
+    get_resource_group("rgname")
+
+# get a storage account
+rg$get_storage_account("mystorage")
+
+}
+}
 \seealso{
 \link{create_storage_account}, \link{delete_storage_account}, \link{az_storage},
 \href{https://docs.microsoft.com/en-us/rest/api/storagerp/}{Azure Storage Provider API reference}

man/storage_endpoint.Rd

@@ -43,6 +43,17 @@ Create a storage endpoint object
 \details{
 This is the starting point for the client-side storage interface in AzureRMR. \code{storage_endpoint} is a generic function to create an endpoint for any type of Azure storage while \code{blob_endpoint} and \code{file_endpoint} create endpoints for those types.
 }
+\examples{
+\dontrun{
+
+# obtaining an endpoint from the storage account resource object
+endp <- stor$get_blob_endpoint()
+
+# creating an endpoint standalone
+endp <- blob_endpoint("https://mystorage.blob.core.windows.net/", key="access_key")
+
+}
+}
 \seealso{
 \link{az_storage}, \link{file_share}, \link{create_file_share}, \link{blob_container}, \link{create_blob_container}
 }