Merge branch 'dev'

* dev:
  Bump version to 0.2.6
  Small changes in Azure Batch functions
  Split message into multiple lines.
  Fix bug in argument naming
  More fixes to vignettes #76
  Document how to use blob store functions without authentication #76
  Fix errors and typos in vignettes #75

DESCRIPTION

@@ -5,12 +5,12 @@ Description: Helps users to manage Azure Services and objects from within an
     Machines and HDInsight (Spark, Hive). To use the package, you must configure an
     Azure Active Directory application and service principal in the Azure portal.
 Type: Package
-Version: 0.2.5
-Date: 2017-06-06
+Version: 0.2.6
+Date: 2017-06-16
 Authors@R: c(
       person(family="Microsoft Corporation", role="cph"),
-      person("Alan", "Weaver", role=c("aut", "cre"), email="[email protected]"),
-      person("Andrie", "de Vries", role=c("aut"), email="[email protected]")
+      person("Alan", "Weaver", role=c("aut"), email="[email protected]"),
+      person("Andrie", "de Vries", role=c("aut", "cre"), email="[email protected]")
     )
 Copyright: Microsoft
 License: MIT + file LICENSE
@@ -28,7 +28,7 @@ Imports:
     miniUI (>= 0.1.1),
     rstudioapi (>= 0.5),
     DT,
-    lubridate,
+    lubridate
 Depends:
     R(>= 3.0.0)
 Suggests:

R/AzureBatch.R

@@ -31,8 +31,11 @@ azureListBatchAccounts <- function(azureActiveContext, resourceGroup, subscripti
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureBatchGetKey
+#' 
 #' @param location A string for the location to create batch account
 #' @param asynchronous If TRUE, submits asynchronous request to Azure. Otherwise waits until batch account is created.
+#'
+#' @references https://docs.microsoft.com/en-us/rest/api/batchmanagement/batchaccount
 #' @family Batch account functions
 #' @export
 azureCreateBatchAccount <- function(azureActiveContext, batchAccount,
@@ -47,9 +50,7 @@ azureCreateBatchAccount <- function(azureActiveContext, batchAccount,
   assert_that(is_subscription_id(subscriptionID))
   assert_that(is_storage_account(batchAccount))
 
-  body <- paste0('{
-                  "location":"', location, '",
-                  }'
+  body <- paste0('{"location":"', location, '"}'
   )  
 
   uri <- paste0("https://management.azure.com/subscriptions/", subscriptionID,
@@ -59,24 +60,16 @@ azureCreateBatchAccount <- function(azureActiveContext, batchAccount,
   r <- call_azure_sm(azureActiveContext, uri = uri, body = body,
                      verb = "PUT", verbose = verbose)
 
-  if (status_code(r) == 409) {
-    message("409: Conflict : Account already exists with the same name")
-    return(TRUE)
-  }
-
-  if (status_code(r) == 200) {
-    message("Account already exists with the same properties")
-  }
   stopWithAzureError(r)
 
-  rl <- content(r, "text", encoding = "UTF-8")
   azureActiveContext$batchAccount <- batchAccount
   azureActiveContext$resourceGroup  <- resourceGroup
-  message("Create request Accepted. It can take a few moments to provision the batch account")
+  message("Create request accepted")
+  message("It can take a few moments to provision the batch account")
 
   if (!asynchronous) {
     wait_for_azure(
-      batchAccount %in% azureListBatchAccounts(azureActiveContext, subscriptionID = subscriptionID)$name
+      batchAccount %in% azureListBatchAccounts(azureActiveContext)$name
     )
   }
   TRUE
@@ -88,7 +81,8 @@ azureCreateBatchAccount <- function(azureActiveContext, batchAccount,
 #' @inheritParams setAzureContext
 #' @inheritParams azureAuthenticate
 #' @inheritParams azureBatchGetKey
-
+#'
+#' @references https://docs.microsoft.com/en-us/rest/api/batchmanagement/batchaccount#BatchAccount_Delete
 #' @family Batch account functions
 #' @export
 azureDeleteBatchAccount <- function(azureActiveContext, batchAccount,

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

R/AzureStorageAccount.R

@@ -123,7 +123,8 @@ azureCreateStorageAccount <- function(azureActiveContext, storageAccount,
   rl <- content(r, "text", encoding = "UTF-8")
   azureActiveContext$storageAccount <- storageAccount
   azureActiveContext$resourceGroup  <- resourceGroup
-  message("Create request Accepted. It can take a few moments to provision the storage account")
+  message("Create request accepted")
+  message("It can take a few moments to provision the storage account")
 
   if (!asynchronous) {
     wait_for_azure(

R/internal.R

@@ -165,7 +165,7 @@ refreshStorageKey <- function(azureActiveContext, storageAccount, resourceGroup)
 
 updateAzureActiveContext <- function(x, storageAccount, storageKey, resourceGroup, container, blob, directory) {
   # updates the active azure context in place
-  assert_that(is.azureActiveContext(azureActiveContext))
+  assert_that(is.azureActiveContext(x))
   if (!missing(storageAccount)) x$storageAccount <- storageAccount
   if (!missing(resourceGroup))  x$resourceGroup  <- resourceGroup
   if (!missing(storageKey))     x$storageKey     <- storageKey
@@ -174,4 +174,3 @@ updateAzureActiveContext <- function(x, storageAccount, storageKey, resourceGrou
   if (!missing(directory)) x$directory <- directory
   TRUE
 }
-

inst/doc/Authentication.Rmd

@@ -1,75 +1,88 @@
 ---
-title: "Getting Authorised for the AzureSMR Package"
+title: "Authenticating AzureSMR to call the Azure API"
 author: "Alan Weaver and Andrie de Vries"
 date: "`r Sys.Date()`"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{AzureSMR tutorial}
+  %\VignetteIndexEntry{AzureSMR authentication}
   %\VignetteEngine{knitr::rmarkdown}
   %\usepackage[utf8]{inputenc}
 ---
 
 ## Configuration instructions
 
-Follow these instructions to create an active directory. You will need to collect the tenant ID (`tenantID`), client ID (`clientID`) and authentication key (`authKey`) in order to authenticate with the `createAzureContect()` function.
+To use the `AzureSMR` package, you must create an Azure Active Directory application with permisssions.  This vignette contains instructions to do this.
 
-### Create an Active Directory App.
+You must collect three pieces of information to authenticate with the `createAzureContect()` function:
 
-1. Login to the Classic (i.e., the old) Portal https://manage.windowsazure.com/.
+* tenant ID (`tenantID`)
+* client ID (`clientID`)
+* authentication key (`authKey`) 
 
-2. On the left hand menu you should see amongst all the items one called ACTIVE DIRECTORY. Click the item and an active directory DIRECTORY will be listed.
+## Create an Active Directory application.
+
+1. Login to the Classic (the old) Portal https://manage.windowsazure.com/.
+
+2. On the left hand menu you should see amongst all the items one called `ACTIVE DIRECTORY`. Click the item and an active directory DIRECTORY will be listed.
 
 3. Click on an entry under the Name column (if there is only one entry the choice is easy!) to take you to a page of options to get started with some text like I WANT TO.
 
-4. Along the top menu click APPLICATIONS.
+4. Along the top menu click `APPLICATIONS`.
 
-5. You probably want to create a new application so type a name for it in the Search box (I called mine AzureSMR). The search result will come back with no results and a button that says `ADD AN APPLICATION` -> which you should click.
+5. You probably want to create a new application so type a name for it in the Search box (I called mine `AzureSMR`). The search result will come back with no results and a button that says `ADD AN APPLICATION` -> which you should click.
 
 6. Give the application a name and choose `WEB APPLICATION AND/OR WEB API`. Then go to the next page `->`.
 
 7. Provide some dummy URLs. They are not used but they must be valid URLs. Click on the tick to continue to create the application.
 
-8. Under the Configure menu button take note of the client ID.9. Under the Keys section choose a 1 year duration (or 2) and click the Save button azToken the bottom of the screen. A key is generated which you should copy now and save it somewhere.
+8. Under the Configure menu button take note of the **client ID**.
+
+9. Under the `Keys` section choose a 1 year duration (or 2) and click the Save button at the bottom of the screen. An **authenticatio key** is generated which you should copy now and save it somewhere.
+
+10. You also need the **tenant ID**. Click the `VIEW ENDPOINTS` button on the bottom of the screen and find a list of endpoints all including the tenant ID as a sequence of hexadecimals.
 
-10. We also need the *tenant ID*. Click the `VIEW ENDPOINTS` button on the bottom of the screen and find a list of endpoints all including the tenant ID as a sequence of hexadecimals.
+11. Now set up the applications permissions. Click the `Add application` button. In  the resulting window scroll to `Windows Azure Service Management API` and select it. Then click the Tick icon.
 
-11. Now we need to set up the applications permissions. Click the `Add application` button. In  the resulting window scroll to `Windows Azure Service Management API` and select it. Then click the Tick icon.
+12. Under the resulting "permissions to other applications" section, for the Windows Azure Service Management API entry, from the `Delegated Permissions` drop down tick the Access Azure Service Management as organization.
 
-12. Under the resulting "permissions to other applications" section, for the Windows Azure Service Management API entry, from the "Delegated Permissions:0" drop down tick the Access Azure Service Management as organization.
+13. Click on the Save icon at the bottom of the window again.
 
-13. Click on the Save icon azToken the bottom of the window again.
+14. Now assign the application a role and to do so you go to the (new) Azure portal. https://portal.azure.com/
 
-14. Now we need to assign the application a role and to do so we go to the (new) Azure portal. https://portal.azure.com/
+## Access control
 
-To apply access control azToken Resource Group
+You can apply access control at either the resource group level or the subscription level
+
+### To apply access control at Resource Group
 
 15. Click on Resource Groups menu item on the left in the portal.
 
 16. Identify the resource group you will associate with this application.
 
-17. Choose the Access Control(IAM) menu item from the Resource scope.
+17. Choose the `Access Control (IAM)` menu item from the Resource scope.
 
 18. In the resulting scope click the `+ Add` button.
 
-19. Choose the role as Owner and under the user search box enter the name of the App, e.g., AzureSMR.
+19. Choose the role as Owner and under the user search box enter the name of the App, e.g. `AzureSMR`.
 
-20. Select the resulting list item for that App then click Select in that scope then OK in the "Add access" scope. The user will be added to the list.
+20. Select the resulting list item for that App then click Select in that scope then OK in the `Add access` scope. The user will be added to the list.
 
 
-Alternatively you can access control azToken Subscription Level
+### Alternatively you can access control at Subscription Level
 
 15. Click on Subscriptions on the left menu item in the portal.
 
 16. Identify the Subscription you will associate with this application.
 
-17. Choose the Access Control(IAM) menu item.
+17. Choose the `Access Control (IAM)` menu item.
 
-18. In the resulting scope click the + Add button.
+18. In the resulting scope click the `+ Add` button.
 
-19. Choose the role as Owner and under the user search box enter the name of the App, e.g., AzureSMR.
+19. Choose the role as Owner and under the user search box enter the name of the App, e.g. `AzureSMR`.
 
 20. Select the resulting list item for that App then click Select in that scope then OK in the "Add access" scope. The user will be added to the list.
 
+## Conclusion
 
 That is all.  You can test this by trying: