зеркало из https://github.com/Azure/AzureRMR.git
documentation
This commit is contained in:
hong-revo
Родитель
aadb2e4654
Коммит
ddcb0624cf
|
|
@ -1,12 +1,13 @@
|
|||
Package: AzureRMR
|
||||
Title: Base functionality for Azure RMR: authenticate, get subscriptions, get resource groups
|
||||
Version: 0.0.1
|
||||
Version: 0.1
|
||||
Authors@R: c(
|
||||
person("Hong", "Ooi", , "hongooi@microsoft.com", role = c("aut", "cre")),
|
||||
person("Microsoft", role="cph")
|
||||
)
|
||||
Description: A package for managing a selection of Azure resources, using the Azure Service Manager API. The package exposes functions to manage subscriptions and resource groups. Managing other types of resources is handled via add-on packages that call AzureSMRbase.
|
||||
License: file LICENSE
|
||||
VignetteBuilder: knitr
|
||||
Encoding: UTF-8
|
||||
Depends:
|
||||
R (>= 3.3)
|
||||
|
|
@ -14,4 +15,5 @@ Imports:
|
|||
httr (>= 1.3),
|
||||
jsonlite,
|
||||
R6
|
||||
Roxygen: list(markdown=TRUE)
|
||||
RoxygenNote: 6.0.1
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
# Generated by roxygen2: do not edit by hand
|
||||
|
||||
export(AzureToken)
|
||||
export(az_context)
|
||||
export(az_resource)
|
||||
export(az_resource_group)
|
||||
export(az_rm)
|
||||
export(az_subscription)
|
||||
export(az_template)
|
||||
export(call_azure_rm)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,19 @@
|
|||
#' Azure OAuth authentication
|
||||
#'
|
||||
#' Azure OAuth 2.0 token class, inheriting from the [Token2.0 class][httr:Token2.0] in httr. Rather than calling the initialization method directly, tokens should be created via [get_azure_token()].
|
||||
#'
|
||||
#' @docType class
|
||||
#' @section Methods:
|
||||
#' - `refresh`: Refreshes the token. For expired Azure tokens using client credentials, refreshing really means requesting a new token.
|
||||
#' - `validate`: Checks if the token is still valid. For Azure tokens using client credentials, this just checks if the current time is less than the token's expiry time.
|
||||
#'
|
||||
#' @section Caching:
|
||||
#' This class never caches its tokens, unlike httr::Token2.0.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [get_azure_token], [httr::Token]
|
||||
#'
|
||||
#' @format An R6 object of class `AzureToken`.
|
||||
#' @export
|
||||
AzureToken <- R6::R6Class("AzureToken", inherit=httr::Token2.0,
|
||||
|
||||
|
|
@ -91,6 +107,24 @@ private=list(
|
|||
))
|
||||
|
||||
|
||||
#' Generate an Azure OAuth token
|
||||
#'
|
||||
#' This extends the OAuth functionality in httr to allow for device code authentication.
|
||||
#'
|
||||
#' @param aad_host URL for your Azure Active Directory host. For the public Azure cloud, this is `https://login.microsoftonline.com/`.
|
||||
#' @param tenant Your tenant ID.
|
||||
#' @param app Your client/app ID which you registered in AAD.
|
||||
#' @param auth_type The authentication type, either `"client_credentials"` or `"device_code"`.
|
||||
#' @param secret Your secret key. Required for `auth_type == "client_credentials"`, ignored for `auth_type == "device_code"`.
|
||||
#' @param arm_host URL for your Azure Resource Manager host. For the public Azure cloud, this is `https://management.azure.com/`.
|
||||
#'
|
||||
#' @details
|
||||
#' This function does much the same thing as [httr::oauth2.0_token()], but with support for device authentication and with unnecessary options removed. Device authentication removes the need to save a secret key on your machine. Instead, the server provides you with a code, along with a URL. You then visit the URL in your browser and enter the code, which completes the authentication process.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [AzureToken], [httr::oauth2.0_token], [httr::Token],
|
||||
#' [https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code],
|
||||
#' [https://www.oauth.com/oauth2-servers/device-flow/token-request/]
|
||||
#' @export
|
||||
get_azure_token=function(aad_host, tenant, app, auth_type=c("client_credentials", "device_code"), secret, arm_host)
|
||||
{
|
||||
|
|
@ -120,7 +154,7 @@ auth_with_device <- function(base_url, app, resource)
|
|||
}
|
||||
|
||||
|
||||
is_token <- function(object)
|
||||
is_azure_token <- function(object)
|
||||
{
|
||||
R6::is.R6(object) && inherits(object, "AzureToken")
|
||||
}
|
||||
|
|
|
|||
32
R/az_auth.R
32
R/az_auth.R
|
|
@ -1,7 +1,33 @@
|
|||
### Azure Context class: authentication functionality for AAD
|
||||
### base Resource Manager class
|
||||
|
||||
#' Azure Resource Manager
|
||||
#'
|
||||
#' Base class for interacting with Azure Resource Manager.
|
||||
#'
|
||||
#' @docType class
|
||||
#' @section Methods:
|
||||
#' - `new(tenant, app, ...)`: Initialize a new ARM connection with the given credentials. See 'Authentication` for more details.
|
||||
#' - `list_subscriptions()`: Returns a list of objects, one for each subscription associated with this app ID.
|
||||
#' - `get_subscription(id)`: Returns an object representing a subscription.
|
||||
#'
|
||||
#' @section Authentication:
|
||||
#' To authenticate with ARM, provide the following arguments to the `new` method:
|
||||
#' - `tenant`: Your tenant ID.
|
||||
#' - `app`: Your client/app ID which you registered in Azure Active Directory.
|
||||
#' - `auth_type`: Either `"client_credentials"` (the default) or `"device_code"`.
|
||||
#' - `secret`: if `auth_type == "client_credentials"`, your secret key.
|
||||
#' - `host`: your ARM host. Defaults to `https://management.azure.com/`. Change this if you are using a government or private cloud.
|
||||
#' - `aad_host`: Azure Active Directory host for authentication. Defaults to `https://login.microsoftonline.com/`. Change this if you are using a government or private cloud.
|
||||
#' - `config_file`: Optionally, a JSON file containing any of the arguments listed above. Arguments supplied in this file take priority over those supplied on the command line.
|
||||
#' - `token`: Optionally, an OAuth 2.0 token, of class [AzureToken]. This allows you to reuse the authentication details for an existing session. If supplied, all other arguments will be ignored.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [get_azure_token], [AzureToken],
|
||||
#' [https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview]
|
||||
#'
|
||||
#' @format An R6 object of class `az_rm`.
|
||||
#' @export
|
||||
az_context <- R6::R6Class("az_context",
|
||||
az_rm <- R6::R6Class("az_rm",
|
||||
|
||||
public=list(
|
||||
host=NULL,
|
||||
|
|
@ -13,7 +39,7 @@ public=list(
|
|||
host="https://management.azure.com/", aad_host="https://login.microsoftonline.com/",
|
||||
config_file=NULL, token=NULL)
|
||||
{
|
||||
if(is_token(token))
|
||||
if(is_azure_token(token))
|
||||
{
|
||||
self$host <- token$credentials$resource
|
||||
self$tenant <- sub("/.+$", "", httr::parse_url(token$endpoint$authorize)$path)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,57 @@
|
|||
#' Azure resource group class
|
||||
#'
|
||||
#' Class representing an Azure resource group.
|
||||
#'
|
||||
#' @docType class
|
||||
#' @section Methods:
|
||||
#' - `new(token, subscription, id, ...)`: Initialize a resource group object. See 'Initialization' for more details.
|
||||
#' - `check()`: Check if this resource group still exists.
|
||||
#' - `delete(confirm=TRUE)`: Delete this resource group, after a confirmation check. This is asynchronous: while the method returns immediately, the delete operation continues on the host in the background. For resource groups containing a large number of deployed resources, this may take some time to complete.
|
||||
#' - `list_templates()`: List deployed templates in this resource group.
|
||||
#' - `get_template(name)`: Return an object representing an existing template.
|
||||
#' - `deploy_template(...)`: Deploy a new template. See 'Templates' for more details.
|
||||
#' - `delete_template(name, confirm=TRUE, free_resources=FALSE)`: Delete a deployed template, and optionally free any resources that were created.
|
||||
#' - `get_resource(...)`: Return an object representing an existing resource. See 'Resources' for more details.
|
||||
#' - `create_resource(...)`: Create a new resource.
|
||||
#' - `delete_resource(..., confirm=TRUE, wait=FALSE)`: Delete an existing resource. Optionally wait for the delete to finish.
|
||||
#' - `list_resources()`: Return a list of resource group objects for this subscription.
|
||||
#'
|
||||
#' @section Initialization:
|
||||
#' Initializing a new object of this class can either retrieve an existing resource group, or create a new resource group on the host. Generally, the easiest way to create a resource group object is via the `get_resource_group`, `create_resource_group` or `list_resource_groups` methods of the [az_subscription] class, which handle this automatically.
|
||||
#'
|
||||
#' To create a resource group object in isolation, supply (at least) an Oauth 2.0 token of class [AzureToken], the subscription ID, and the resource group name. If this object refers to a _new_ resource group, supply the location as well (use the `list_locations` method of the `az_subscription class` for possible locations). You can also pass any optional parameters for the resource group as named arguments to `new()`.
|
||||
#'
|
||||
#' @section Templates:
|
||||
#' To deploy a new template, pass the following arguments to `deploy_template()`:
|
||||
#' - `name`: The name of the deployment.
|
||||
#' - `template`: The template to deploy. This can be provided in a number of ways:
|
||||
#' 1. A nested list of name-value pairs representing the parsed JSON
|
||||
#' 2. The name of a template file
|
||||
#' 3. A vector of strings containing unparsed JSON
|
||||
#' 4. A URL from which the template can be downloaded
|
||||
#' - `parameters`: The parameters for the template. This can be provided using any of the same methods as the `template` argument.
|
||||
#'
|
||||
#' Retrieving or deleting a deployed template requires only the name of the deployment.
|
||||
#'
|
||||
#' @section Resources:
|
||||
#' There are a number of arguments to `get_resource()`, `create_resource()` and `delete_resource()` that serve to identify the specific resource in question:
|
||||
#' - `id`: The full ID of the resource, including subscription ID and resource group.
|
||||
#' - `provider`: The provider of the resource, eg `Microsoft.Compute`.
|
||||
#' - `path`: The full path to the resource, eg `virtualMachines`.
|
||||
#' - `type`: The combination of provider and path, eg `Microsoft.Compute/virtualMachines`.
|
||||
#' - `name`: The name of the resource instance, eg `myWindowsVM`.
|
||||
#'
|
||||
#' Providing the `id` argument will fill in the values for all the other arguments. Similarly, providing the `type` argument will fill in the values for `provider` and `path`. Unless you provide `id`, you must also provide `name`.
|
||||
#'
|
||||
#' To create/deploy a new resource, specify any extra parameters that the provider needs as named arguments to `create_resource()`.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [az_subscription], [az_template], [az_resource],
|
||||
#' [https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview#resource-groups],
|
||||
#' [https://docs.microsoft.com/en-us/rest/api/resources/resources],
|
||||
#' [https://docs.microsoft.com/en-us/rest/api/resources/deployments]
|
||||
#'
|
||||
#' @format An R6 object of class `az_resource_group`.
|
||||
#' @export
|
||||
az_resource_group <- R6::R6Class("az_resource_group",
|
||||
|
||||
|
|
@ -71,20 +125,20 @@ public=list(
|
|||
named_list(lst)
|
||||
},
|
||||
|
||||
deploy_template=function(template_name, template, parameters, ...)
|
||||
deploy_template=function(name, template, parameters, ...)
|
||||
{
|
||||
az_template$new(self$token, self$subscription, self$name, template_name,
|
||||
az_template$new(self$token, self$subscription, self$name, name,
|
||||
template, parameters, ...)
|
||||
},
|
||||
|
||||
get_template=function(template_name)
|
||||
get_template=function(name)
|
||||
{
|
||||
az_template$new(self$token, self$subscription, self$name, template_name)
|
||||
az_template$new(self$token, self$subscription, self$name, name)
|
||||
},
|
||||
|
||||
delete_template=function(template_name, confirm=TRUE, free_resources=FALSE)
|
||||
delete_template=function(name, confirm=TRUE, free_resources=FALSE)
|
||||
{
|
||||
self$get_template(template_name)$delete(confirm=confirm, free_resources=free_resources)
|
||||
self$get_template(name)$delete(confirm=confirm, free_resources=free_resources)
|
||||
},
|
||||
|
||||
list_resources=function()
|
||||
|
|
|
|||
|
|
@ -1,3 +1,48 @@
|
|||
#' Azure resource class
|
||||
#'
|
||||
#' Class representing a generic Azure resource.
|
||||
#'
|
||||
#' @docType class
|
||||
#' @section Methods:
|
||||
#' - `new(...)`: Initialize a new resource object. See 'Initialization' for more details.
|
||||
#' - `check()`: Check if this resource still exists.
|
||||
#' - `delete(confirm=TRUE, wait=FALSE)`: Delete this resource, after a confirmation check. Optionally wait for the delete to finish.
|
||||
#' - `update(...)`: Update this resource on the host.
|
||||
#' - `sync_fields()`: Update the fields in this object with information from the host.
|
||||
#' - `set_api_version(api_version)`: Set the API version to use when interacting with the host. By default, use the latest API version available.
|
||||
#' - `do_operation(...)` Carry out an operation. See `Operations` for more details.
|
||||
#'
|
||||
#' @section Initialization:
|
||||
#' There are multiple ways to initialize a new resource object. You can either retrieve an existing resource, or deploy a new resource on the host. Generally, the easiest way to create a new object is via the `get_resource`, `create_resource` or `list_resources` methods of the [az_resource_group] class, which will handle the details automatically.
|
||||
#'
|
||||
#' To initialize a resource object from scratch, supply the following arguments to `new()`:
|
||||
#' - `token`: An Oauth 2.0 token, as generated by [get_azure_token].
|
||||
#' - `subscription`: The subscription ID.
|
||||
#' - `resource_group`: The resource group.
|
||||
#'
|
||||
#' There are also a number of _identifying arguments_ to `new()` that are used to refer to a specific resource:
|
||||
#' - `id`: The full ID of the resource, including subscription ID and resource group.
|
||||
#' - `provider`: The provider of the resource, eg `Microsoft.Compute`.
|
||||
#' - `path`: The full path to the resource, eg `virtualMachines`.
|
||||
#' - `type`: The combination of provider and path, eg `Microsoft.Compute/virtualMachines`.
|
||||
#' - `name`: The name of the resource instance, eg `myWindowsVM`.
|
||||
#'
|
||||
#' Providing the `id` argument will fill in the values for all the other arguments. Similarly, providing the `type` argument will fill in the values for `provider` and `path`. Unless you provide `id`, you must also provide `name`. If you provide only these identifying arguments to `new()`, it is assumed that you want to retrieve an existing resource. Passing any further (named) arguments will create a new resource, with the supplied arguments as parameters.
|
||||
#'
|
||||
#' @section Operations:
|
||||
#' The `do_operation()` method allows you to carry out arbitrary operations on the resource. It takes the following arguments:
|
||||
#' - `http_verb`: The HTTP verb as a string, one of `GET`, `PUT`, `POST`, `DELETE`, `HEAD` or `PATCH`.
|
||||
#' - `op`: The operation in question, which will be appended to the URL path of the request.
|
||||
#' - `options`: A named list giving the URL query parameters.
|
||||
#' - `...`: Other named arguments passed to [call_azure_rm], and then to the appropriate call in httr. In particular, use `body` to supply the body of a request.
|
||||
#'
|
||||
#' Consult the Azure documentation for your resource to find out what operations are supported.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [az_resource_group], [call_azure_rm], [call_azure_url],
|
||||
#' [https://docs.microsoft.com/en-us/rest/api/resources/resources]
|
||||
#'
|
||||
#' @format An R6 object of class `az_resource`.
|
||||
#' @export
|
||||
az_resource <- R6::R6Class("az_resource",
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,27 @@
|
|||
### Azure subscription class: all info about a subscription
|
||||
|
||||
#' Azure subscription class
|
||||
#'
|
||||
#' Class representing an Azure subscription.
|
||||
#'
|
||||
#' @docType class
|
||||
#' @section Methods:
|
||||
#' - `new(token, id, ...)`: Initialize a subscription object.
|
||||
#' - `list_resource_groups()`: Return a list of resource group objects for this subscription.
|
||||
#' - `get_resource_group(name)`: Return an object representing an existing resource group.
|
||||
#' - `create_resource_group(name, location)`: Create a new resource group in the specified region/location, and return an object representing it.
|
||||
#' - `delete_resource_group(name)`: Delete a resource group.
|
||||
#' - `list_resources()`: List all resources deployed under this subscription.
|
||||
#' - `list_locations()`: List locations available.
|
||||
#' - `get_provider_api_version(provider, type)`: Get the current API version for the given resource provider and type. If no resource type is supplied, returns a vector of API versions, one for each resource type for the given provider. If neither provider nor type is supplied, returns the API versions for all resources and providers.
|
||||
#'
|
||||
#' @section Details:
|
||||
#' Generally, the easiest way to create a subscription object is via the `get_subscription` or `list_subscriptions` methods of the [az_rm] class. To create a subscription object in isolation, call the `new()` method and supply an Oauth 2.0 token of class [AzureToken], along with the ID of the subscription.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview]
|
||||
#'
|
||||
#' @format An R6 object of class `az_subscription`.
|
||||
#' @export
|
||||
az_subscription <- R6::R6Class("az_subscription",
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,36 @@
|
|||
#' Azure template class
|
||||
#'
|
||||
#' Class representing an Azure deployment template.
|
||||
#'
|
||||
#' @docType class
|
||||
#' @section Methods:
|
||||
#' - `new(token, subscription, resource_group, name, ...)`: Initialize a new template object. See 'Initialization' for more details.
|
||||
#' - `check()`: Check if this deployment template still exists.
|
||||
#' - `cancel(free_resources=FALSE)`: Cancel an in-progress deployment. Optionally free any resources that have already been created.
|
||||
#' - `delete(confirm=TRUE, free_resources=FALSE)`: Delete a deployed template, after a confirmation check. Optionally free any resources that were created.
|
||||
#'
|
||||
#' @section Initialization:
|
||||
#' Initializing a new object of this class can either retrieve an existing template, or deploy a new template on the host. Generally, the easiest way to create a template object is via the `get_template`, `deploy_template` or `list_templates` methods of the [az_resource_group] class, which handle the details automatically.
|
||||
#'
|
||||
#' To initialize an object that refers to an existing deployment, supply the following arguments to `new()`:
|
||||
#' - `token`: An Oauth 2.0 token, as generated by [get_azure_token].
|
||||
#' - `subscription`: The subscription ID.
|
||||
#' - `resource_group`: The resource group.
|
||||
#' - `name`: The deployment name`.
|
||||
#'
|
||||
#' If you also supply the following arguments to new(), a new template will be deployed:
|
||||
#' - `template`: The template to deploy. This can be provided in a number of ways:
|
||||
#' 1. A nested list of name-value pairs representing the parsed JSON
|
||||
#' 2. The name of a template file
|
||||
#' 3. A vector of strings containing unparsed JSON
|
||||
#' 4. A URL from which the template can be downloaded
|
||||
#' - `parameters`: The parameters for the template. This can be provided using any of the same methods as the `template` argument.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [az_resource_group], [az_resource],
|
||||
#' [https://docs.microsoft.com/en-us/rest/api/resources/deployments]
|
||||
#'
|
||||
#' @format An R6 object of class `az_template`.
|
||||
#' @export
|
||||
az_template <- R6::R6Class("az_template",
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,27 @@
|
|||
#' Call the Azure Resource Manager REST API
|
||||
#'
|
||||
#' @param token An Azure OAuth token, of class [AzureToken].
|
||||
#' @param subscription A subscription ID.
|
||||
#' @param operation: The operation to perform, which will form part of the URL path.
|
||||
#' @param options: A named list giving the URL query parameters.
|
||||
#' @param api_version: The API version to use, which will form part of the URL sent to the host.
|
||||
#' @param url: A complete URL to send to the host.
|
||||
#' @param http_verb: The HTTP verb as a string, one of `GET`, `PUT`, `POST`, `DELETE`, `HEAD` or `PATCH`.
|
||||
#' @param http_status_handler: How to handle in R the HTTP status code of a response. `"stop"`, `"warn"` or `"message"` will call the appropriate handlers in httr, while `"pass"` ignores the status code.
|
||||
#' @param auto_refresh: Whether to refresh/renew the OAuth token if it is no longer valid.
|
||||
#' @param ... Other arguments passed to lower-level code, ultimately to the appropriate functions in httr.
|
||||
#'
|
||||
#' @details
|
||||
#' These functions form the low-level interface between R and Resource Manager. `call_azure_rm` builds a URL from its arguments and passes it to `call_azure_url`. Authentication is handled automatically.
|
||||
#'
|
||||
#' @return
|
||||
#' If `http_status_handler` is one of `"stop"`, `"warn"` or `"message"`, the status code of the response is checked. If an error is not thrown, the parsed content of the response is returned with the status code attached as the "status" attribute.
|
||||
#'
|
||||
#' If `http_status_handler` is `"pass"`, the entire response is returned without modification.
|
||||
#'
|
||||
#' @seealso
|
||||
#' [httr:GET], [httr:stop_for_status], [httr:content]
|
||||
#' @rdname call_azure
|
||||
#' @export
|
||||
call_azure_rm <- function(token, subscription, operation, ...,
|
||||
options=list(),
|
||||
|
|
@ -11,6 +35,7 @@ call_azure_rm <- function(token, subscription, operation, ...,
|
|||
}
|
||||
|
||||
|
||||
#' @rdname call_azure
|
||||
#' @export
|
||||
call_azure_url <- function(token, url, ...,
|
||||
http_verb=c("GET", "DELETE", "PUT", "POST", "HEAD", "PATCH"),
|
||||
|
|
|
|||
|
|
@ -0,0 +1,30 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/AzureToken.R
|
||||
\docType{class}
|
||||
\name{AzureToken}
|
||||
\alias{AzureToken}
|
||||
\title{Azure OAuth authentication}
|
||||
\format{An R6 object of class \code{AzureToken}.}
|
||||
\usage{
|
||||
AzureToken
|
||||
}
|
||||
\description{
|
||||
Azure OAuth 2.0 token class, inheriting from the \link[=httr:Token2.0]{Token2.0 class} in httr. Rather than calling the initialization method directly, tokens should be created via \code{\link[=get_azure_token]{get_azure_token()}}.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{refresh}: Refreshes the token. For expired Azure tokens using client credentials, refreshing really means requesting a new token.
|
||||
\item \code{validate}: Checks if the token is still valid. For Azure tokens using client credentials, this just checks if the current time is less than the token's expiry time.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Caching}{
|
||||
|
||||
This class never caches its tokens, unlike httr::Token2.0.
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{get_azure_token}, \link[httr:Token]{httr::Token}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/az_resource.R
|
||||
\docType{class}
|
||||
\name{az_resource}
|
||||
\alias{az_resource}
|
||||
\title{Azure resource class}
|
||||
\format{An R6 object of class \code{az_resource}.}
|
||||
\usage{
|
||||
az_resource
|
||||
}
|
||||
\description{
|
||||
Class representing a generic Azure resource.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{new(...)}: Initialize a new resource object. See 'Initialization' for more details.
|
||||
\item \code{check()}: Check if this resource still exists.
|
||||
\item \code{delete(confirm=TRUE, wait=FALSE)}: Delete this resource, after a confirmation check. Optionally wait for the delete to finish.
|
||||
\item \code{update(...)}: Update this resource on the host.
|
||||
\item \code{sync_fields()}: Update the fields in this object with information from the host.
|
||||
\item \code{set_api_version(api_version)}: Set the API version to use when interacting with the host. By default, use the latest API version available.
|
||||
\item \code{do_operation(...)} Carry out an operation. See \code{Operations} for more details.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Initialization}{
|
||||
|
||||
There are multiple ways to initialize a new resource object. You can either retrieve an existing resource, or deploy a new resource on the host. Generally, the easiest way to create a new object is via the \code{get_resource}, \code{create_resource} or \code{list_resources} methods of the \link{az_resource_group} class, which will handle the details automatically.
|
||||
|
||||
To initialize a resource object from scratch, supply the following arguments to \code{new()}:
|
||||
\itemize{
|
||||
\item \code{token}: An Oauth 2.0 token, as generated by \link{get_azure_token}.
|
||||
\item \code{subscription}: The subscription ID.
|
||||
\item \code{resource_group}: The resource group.
|
||||
}
|
||||
|
||||
There are also a number of \emph{identifying arguments} to \code{new()} that are used to refer to a specific resource:
|
||||
\itemize{
|
||||
\item \code{id}: The full ID of the resource, including subscription ID and resource group.
|
||||
\item \code{provider}: The provider of the resource, eg \code{Microsoft.Compute}.
|
||||
\item \code{path}: The full path to the resource, eg \code{virtualMachines}.
|
||||
\item \code{type}: The combination of provider and path, eg \code{Microsoft.Compute/virtualMachines}.
|
||||
\item \code{name}: The name of the resource instance, eg \code{myWindowsVM}.
|
||||
}
|
||||
|
||||
Providing the \code{id} argument will fill in the values for all the other arguments. Similarly, providing the \code{type} argument will fill in the values for \code{provider} and \code{path}. Unless you provide \code{id}, you must also provide \code{name}. If you provide only these identifying arguments to \code{new()}, it is assumed that you want to retrieve an existing resource. Passing any further (named) arguments will create a new resource, with the supplied arguments as parameters.
|
||||
}
|
||||
|
||||
\section{Operations}{
|
||||
|
||||
The \code{do_operation()} method allows you to carry out arbitrary operations on the resource. It takes the following arguments:
|
||||
\itemize{
|
||||
\item \code{http_verb}: The HTTP verb as a string, one of \code{GET}, \code{PUT}, \code{POST}, \code{DELETE}, \code{HEAD} or \code{PATCH}.
|
||||
\item \code{op}: The operation in question, which will be appended to the URL path of the request.
|
||||
\item \code{options}: A named list giving the URL query parameters.
|
||||
\item \code{...}: Other named arguments passed to \link{call_azure_rm}, and then to the appropriate call in httr. In particular, use \code{body} to supply the body of a request.
|
||||
}
|
||||
|
||||
Consult the Azure documentation for your resource to find out what operations are supported.
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{az_resource_group}, \link{call_azure_rm}, \link{call_azure_url},
|
||||
\link{https://docs.microsoft.com/en-us/rest/api/resources/resources}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/az_resgroup.R
|
||||
\docType{class}
|
||||
\name{az_resource_group}
|
||||
\alias{az_resource_group}
|
||||
\title{Azure resource group class}
|
||||
\format{An R6 object of class \code{az_resource_group}.}
|
||||
\usage{
|
||||
az_resource_group
|
||||
}
|
||||
\description{
|
||||
Class representing an Azure resource group.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{new(token, subscription, id, ...)}: Initialize a resource group object. See 'Initialization' for more details.
|
||||
\item \code{check()}: Check if this resource group still exists.
|
||||
\item \code{delete(confirm=TRUE)}: Delete this resource group, after a confirmation check. This is asynchronous: while the method returns immediately, the delete operation continues on the host in the background. For resource groups containing a large number of deployed resources, this may take some time to complete.
|
||||
\item \code{list_templates()}: List deployed templates in this resource group.
|
||||
\item \code{get_template(name)}: Return an object representing an existing template.
|
||||
\item \code{deploy_template(...)}: Deploy a new template. See 'Templates' for more details.
|
||||
\item \code{delete_template(name, confirm=TRUE, free_resources=FALSE)}: Delete a deployed template, and optionally free any resources that were created.
|
||||
\item \code{get_resource(...)}: Return an object representing an existing resource. See 'Resources' for more details.
|
||||
\item \code{create_resource(...)}: Create a new resource.
|
||||
\item \code{delete_resource(..., confirm=TRUE, wait=FALSE)}: Delete an existing resource. Optionally wait for the delete to finish.
|
||||
\item \code{list_resources()}: Return a list of resource group objects for this subscription.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Initialization}{
|
||||
|
||||
Initializing a new object of this class can either retrieve an existing resource group, or create a new resource group on the host. Generally, the easiest way to create a resource group object is via the \code{get_resource_group}, \code{create_resource_group} or \code{list_resource_groups} methods of the \link{az_subscription} class, which handle this automatically.
|
||||
|
||||
To create a resource group object in isolation, supply (at least) an Oauth 2.0 token of class \link{AzureToken}, the subscription ID, and the resource group name. If this object refers to a \emph{new} resource group, supply the location as well (use the \code{list_locations} method of the \code{az_subscription class} for possible locations). You can also pass any optional parameters for the resource group as named arguments to \code{new()}.
|
||||
}
|
||||
|
||||
\section{Templates}{
|
||||
|
||||
To deploy a new template, pass the following arguments to \code{deploy_template()}:
|
||||
\itemize{
|
||||
\item \code{name}: The name of the deployment.
|
||||
\item \code{template}: The template to deploy. This can be provided in a number of ways:
|
||||
\enumerate{
|
||||
\item A nested list of name-value pairs representing the parsed JSON
|
||||
\item The name of a template file
|
||||
\item A vector of strings containing unparsed JSON
|
||||
\item A URL from which the template can be downloaded
|
||||
}
|
||||
\item \code{parameters}: The parameters for the template. This can be provided using any of the same methods as the \code{template} argument.
|
||||
}
|
||||
|
||||
Retrieving or deleting a deployed template requires only the name of the deployment.
|
||||
}
|
||||
|
||||
\section{Resources}{
|
||||
|
||||
There are a number of arguments to \code{get_resource()}, \code{create_resource()} and \code{delete_resource()} that serve to identify the specific resource in question:
|
||||
\itemize{
|
||||
\item \code{id}: The full ID of the resource, including subscription ID and resource group.
|
||||
\item \code{provider}: The provider of the resource, eg \code{Microsoft.Compute}.
|
||||
\item \code{path}: The full path to the resource, eg \code{virtualMachines}.
|
||||
\item \code{type}: The combination of provider and path, eg \code{Microsoft.Compute/virtualMachines}.
|
||||
\item \code{name}: The name of the resource instance, eg \code{myWindowsVM}.
|
||||
}
|
||||
|
||||
Providing the \code{id} argument will fill in the values for all the other arguments. Similarly, providing the \code{type} argument will fill in the values for \code{provider} and \code{path}. Unless you provide \code{id}, you must also provide \code{name}.
|
||||
|
||||
To create/deploy a new resource, specify any extra parameters that the provider needs as named arguments to \code{create_resource()}.
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{az_subscription}, \link{az_template}, \link{az_resource},
|
||||
\link{https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview#resource-groups},
|
||||
\link{https://docs.microsoft.com/en-us/rest/api/resources/resources},
|
||||
\link{https://docs.microsoft.com/en-us/rest/api/resources/deployments}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/az_auth.R
|
||||
\docType{class}
|
||||
\name{az_rm}
|
||||
\alias{az_rm}
|
||||
\title{Azure Resource Manager}
|
||||
\format{An R6 object of class \code{az_rm}.}
|
||||
\usage{
|
||||
az_rm
|
||||
}
|
||||
\description{
|
||||
Base class for interacting with Azure Resource Manager.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{new(tenant, app, ...)}: Initialize a new ARM connection with the given credentials. See 'Authentication` for more details.
|
||||
\item \code{list_subscriptions()}: Returns a list of objects, one for each subscription associated with this app ID.
|
||||
\item \code{get_subscription(id)}: Returns an object representing a subscription.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Authentication}{
|
||||
|
||||
To authenticate with ARM, provide the following arguments to the \code{new} method:
|
||||
\itemize{
|
||||
\item \code{tenant}: Your tenant ID.
|
||||
\item \code{app}: Your client/app ID which you registered in Azure Active Directory.
|
||||
\item \code{auth_type}: Either \code{"client_credentials"} (the default) or \code{"device_code"}.
|
||||
\item \code{secret}: if \code{auth_type == "client_credentials"}, your secret key.
|
||||
\item \code{host}: your ARM host. Defaults to \code{https://management.azure.com/}. Change this if you are using a government or private cloud.
|
||||
\item \code{aad_host}: Azure Active Directory host for authentication. Defaults to \code{https://login.microsoftonline.com/}. Change this if you are using a government or private cloud.
|
||||
\item \code{config_file}: Optionally, a JSON file containing any of the arguments listed above. Arguments supplied in this file take priority over those supplied on the command line.
|
||||
\item \code{token}: Optionally, an OAuth 2.0 token, of class \link{AzureToken}. This allows you to reuse the authentication details for an existing session. If supplied, all other arguments will be ignored.
|
||||
}
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{get_azure_token}, \link{AzureToken},
|
||||
\link{https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/az_subscription.R
|
||||
\docType{class}
|
||||
\name{az_subscription}
|
||||
\alias{az_subscription}
|
||||
\title{Azure subscription class}
|
||||
\format{An R6 object of class \code{az_subscription}.}
|
||||
\usage{
|
||||
az_subscription
|
||||
}
|
||||
\description{
|
||||
Class representing an Azure subscription.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{new(token, id, ...)}: Initialize a subscription object.
|
||||
\item \code{list_resource_groups()}: Return a list of resource group objects for this subscription.
|
||||
\item \code{get_resource_group(name)}: Return an object representing an existing resource group.
|
||||
\item \code{create_resource_group(name, location)}: Create a new resource group in the specified region/location, and return an object representing it.
|
||||
\item \code{delete_resource_group(name)}: Delete a resource group.
|
||||
\item \code{list_resources()}: List all resources deployed under this subscription.
|
||||
\item \code{list_locations()}: List locations available.
|
||||
\item \code{get_provider_api_version(provider, type)}: Get the current API version for the given resource provider and type. If no resource type is supplied, returns a vector of API versions, one for each resource type for the given provider. If neither provider nor type is supplied, returns the API versions for all resources and providers.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Details}{
|
||||
|
||||
Generally, the easiest way to create a subscription object is via the \code{get_subscription} or \code{list_subscriptions} methods of the \link{az_rm} class. To create a subscription object in isolation, call the \code{new()} method and supply an Oauth 2.0 token of class \link{AzureToken}, along with the ID of the subscription.
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-group-overview}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -0,0 +1,53 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/az_template.R
|
||||
\docType{class}
|
||||
\name{az_template}
|
||||
\alias{az_template}
|
||||
\title{Azure template class}
|
||||
\format{An R6 object of class \code{az_template}.}
|
||||
\usage{
|
||||
az_template
|
||||
}
|
||||
\description{
|
||||
Class representing an Azure deployment template.
|
||||
}
|
||||
\section{Methods}{
|
||||
|
||||
\itemize{
|
||||
\item \code{new(token, subscription, resource_group, name, ...)}: Initialize a new template object. See 'Initialization' for more details.
|
||||
\item \code{check()}: Check if this deployment template still exists.
|
||||
\item \code{cancel(free_resources=FALSE)}: Cancel an in-progress deployment. Optionally free any resources that have already been created.
|
||||
\item \code{delete(confirm=TRUE, free_resources=FALSE)}: Delete a deployed template, after a confirmation check. Optionally free any resources that were created.
|
||||
}
|
||||
}
|
||||
|
||||
\section{Initialization}{
|
||||
|
||||
Initializing a new object of this class can either retrieve an existing template, or deploy a new template on the host. Generally, the easiest way to create a template object is via the \code{get_template}, \code{deploy_template} or \code{list_templates} methods of the \link{az_resource_group} class, which handle the details automatically.
|
||||
|
||||
To initialize an object that refers to an existing deployment, supply the following arguments to \code{new()}:
|
||||
\itemize{
|
||||
\item \code{token}: An Oauth 2.0 token, as generated by \link{get_azure_token}.
|
||||
\item \code{subscription}: The subscription ID.
|
||||
\item \code{resource_group}: The resource group.
|
||||
\item \code{name}: The deployment name`.
|
||||
}
|
||||
|
||||
If you also supply the following arguments to new(), a new template will be deployed:
|
||||
\itemize{
|
||||
\item \code{template}: The template to deploy. This can be provided in a number of ways:
|
||||
\enumerate{
|
||||
\item A nested list of name-value pairs representing the parsed JSON
|
||||
\item The name of a template file
|
||||
\item A vector of strings containing unparsed JSON
|
||||
\item A URL from which the template can be downloaded
|
||||
}
|
||||
\item \code{parameters}: The parameters for the template. This can be provided using any of the same methods as the \code{template} argument.
|
||||
}
|
||||
}
|
||||
|
||||
\seealso{
|
||||
\link{az_resource_group}, \link{az_resource},
|
||||
\link{https://docs.microsoft.com/en-us/rest/api/resources/deployments}
|
||||
}
|
||||
\keyword{datasets}
|
||||
|
|
@ -0,0 +1,47 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/call_azure_rm.R
|
||||
\name{call_azure_rm}
|
||||
\alias{call_azure_rm}
|
||||
\alias{call_azure_url}
|
||||
\title{Call the Azure Resource Manager REST API}
|
||||
\usage{
|
||||
call_azure_rm(token, subscription, operation, ..., options = list(),
|
||||
api_version = getOption("azure_api_version"))
|
||||
|
||||
call_azure_url(token, url, ..., http_verb = c("GET", "DELETE", "PUT", "POST",
|
||||
"HEAD", "PATCH"), http_status_handler = c("stop", "warn", "message",
|
||||
"pass"), auto_refresh = TRUE)
|
||||
}
|
||||
\arguments{
|
||||
\item{token}{An Azure OAuth token, of class \link{AzureToken}.}
|
||||
|
||||
\item{subscription}{A subscription ID.}
|
||||
|
||||
\item{...}{Other arguments passed to lower-level code, ultimately to the appropriate functions in httr.}
|
||||
|
||||
\item{operation:}{The operation to perform, which will form part of the URL path.}
|
||||
|
||||
\item{options:}{A named list giving the URL query parameters.}
|
||||
|
||||
\item{api_version:}{The API version to use, which will form part of the URL sent to the host.}
|
||||
|
||||
\item{url:}{A complete URL to send to the host.}
|
||||
|
||||
\item{http_verb:}{The HTTP verb as a string, one of \code{GET}, \code{PUT}, \code{POST}, \code{DELETE}, \code{HEAD} or \code{PATCH}.}
|
||||
|
||||
\item{http_status_handler:}{How to handle in R the HTTP status code of a response. \code{"stop"}, \code{"warn"} or \code{"message"} will call the appropriate handlers in httr, while \code{"pass"} ignores the status code.}
|
||||
|
||||
\item{auto_refresh:}{Whether to refresh/renew the OAuth token if it is no longer valid.}
|
||||
}
|
||||
\value{
|
||||
If \code{http_status_handler} is one of \code{"stop"}, \code{"warn"} or \code{"message"}, the status code of the response is checked and if an error is not thrown, the content of the response is returned with the status code attached as the "status" attribute. If \code{http_status_handler} is \code{"pass"}, the entire response is returned without modification.
|
||||
}
|
||||
\description{
|
||||
Call the Azure Resource Manager REST API
|
||||
}
|
||||
\details{
|
||||
These functions form the low-level interface between R and Resource Manager. \code{call_azure_rm} builds a URL from its arguments and passes it to \code{call_azure_url}. Authentication is handled automatically.
|
||||
}
|
||||
\seealso{
|
||||
\link{httr:GET}, \link{httr:stop_for_status}, \link{httr:content}
|
||||
}
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
% Generated by roxygen2: do not edit by hand
|
||||
% Please edit documentation in R/AzureToken.R
|
||||
\name{get_azure_token}
|
||||
\alias{get_azure_token}
|
||||
\title{Generate an Azure OAuth token}
|
||||
\usage{
|
||||
get_azure_token(aad_host, tenant, app, auth_type = c("client_credentials",
|
||||
"device_code"), secret, arm_host)
|
||||
}
|
||||
\arguments{
|
||||
\item{aad_host}{URL for your Azure Active Directory host. For the public Azure cloud, this is \code{https://login.microsoftonline.com/}.}
|
||||
|
||||
\item{tenant}{Your tenant ID.}
|
||||
|
||||
\item{app}{Your client/app ID which you registered in AAD.}
|
||||
|
||||
\item{auth_type}{The authentication type, either \code{"client_credentials"} or \code{"device_code"}.}
|
||||
|
||||
\item{secret}{Your secret key. Required for \code{auth_type == "client_credentials"}, ignored for \code{auth_type == "device_code"}.}
|
||||
|
||||
\item{arm_host}{URL for your Azure Resource Manager host. For the public Azure cloud, this is \code{https://management.azure.com/}.}
|
||||
}
|
||||
\description{
|
||||
This extends the OAuth functionality in httr to allow for device code authentication.
|
||||
}
|
||||
\details{
|
||||
This function does much the same thing as \code{\link[httr:oauth_2.0_token]{httr::oauth_2.0_token()}}, but with support for device authentication and with unnecessary options removed. Device authentication removes the need to save a secret key on your machine. Instead, the server provides you with a code, along with a URL. You then visit the URL in your browser and enter the code, which completes the authentication process.
|
||||
}
|
||||
\seealso{
|
||||
\link{AzureToken}, \link[httr:oauth2.0_token]{httr::oauth2.0_token}, \link[httr:Token]{httr::Token},
|
||||
\link{https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols-oauth-code},
|
||||
\link{https://www.oauth.com/oauth2-servers/device-flow/token-request/}
|
||||
}
|
||||
|
|
@ -1,25 +1,24 @@
|
|||
---
|
||||
title: "Authenticating AzureSMR to call the Azure API"
|
||||
author: "Hong Ooi, after Alan Weaver and Andrie de Vries"
|
||||
date: "`r Sys.Date()`"
|
||||
title: "Registering a client app with Azure Active Directory"
|
||||
Author: Hong Ooi, after Alan Weaver and Andrie de Vries
|
||||
output: rmarkdown::html_vignette
|
||||
vignette: >
|
||||
%\VignetteIndexEntry{AzureSMR authentication}
|
||||
%\VignetteIndexEntry{Azure Active Directory app registration}
|
||||
%\VignetteEngine{knitr::rmarkdown}
|
||||
%\usepackage[utf8]{inputenc}
|
||||
%\VignetteEncoding{utf8}
|
||||
---
|
||||
|
||||
## Configuration instructions
|
||||
|
||||
To use the `AzureSMR` package, you must create an Azure Active Directory application with permisssions. This vignette contains instructions to do this.
|
||||
To use the `AzureRMR` package, you must create an Azure Active Directory application with permisssions. This vignette contains instructions to do this.
|
||||
|
||||
You must collect three pieces of information to authenticate with the `createAzureContext()` function:
|
||||
You must collect at least two pieces of information to authenticate with `az_rm()`, possibly three:
|
||||
|
||||
* tenant ID (`tenantID`)
|
||||
* application ID (`appID`)
|
||||
* secret key (`secret`)
|
||||
* tenant ID (`tenant`)
|
||||
* application ID (`app`)
|
||||
* secret key (`secret`) optionally, if using client credentials: see later
|
||||
|
||||
## Create an Active Directory application.
|
||||
## Create an Active Directory application
|
||||
|
||||
1. Login to the [Azure Portal](https://portal.azure.com).
|
||||
|
||||
|
|
@ -31,7 +30,7 @@ You must collect three pieces of information to authenticate with the `createAzu
|
|||
|
||||
1. In the Create blade, enter the details for your new application. The name should be unique. It doesn't matter what sign-on URL you provide (it won't be used), but it must be a valid URL.
|
||||
|
||||
1. In the "Application type" box, choose "Web App/API" if you want to authenticate using a secret key, or "Native" if you want to authenticate with a code that the server sends to you at runtime. If you're not sure, choose "Native" as this provides more security.
|
||||
1. In the "Application type" box, choose "Web App/API" if you want to authenticate using a secret key, or "Native" if you want to authenticate with a code that the server sends to you at runtime. If you're not sure, choose "Native" as this provides more security. If you intend to use AzureRMR in a scripted setting (without user intervention), choose "Web App".
|
||||
|
||||
1. Click on "Create". After a few seconds, a new blade will appear containing a list of all registered AAD applications.
|
||||
|
||||
|
|
@ -93,18 +92,19 @@ Azure lets you apply access controls at multiple levels: by subscription, by res
|
|||
|
||||
## Conclusion
|
||||
|
||||
That is all. You can test this by trying:
|
||||
You can test this by trying:
|
||||
|
||||
```{r, eval = FALSE}
|
||||
sc <- az_context$new(tenant_id="{TID}", app_id="{CID}", secret="{KEY}")
|
||||
library(AzureRMR)
|
||||
sc <- az_rm$new(tenant="{TID}", app="{CID}", secret="{KEY}")
|
||||
sc
|
||||
```
|
||||
|
||||
or using two-factor authentication if supported by that resource by trying:
|
||||
or using device authentication by trying:
|
||||
|
||||
```{r, eval = FALSE}
|
||||
sc <- az_context$new(tenant_id="{TID}", app_id="{CID}", auth_type="device")
|
||||
# Manually authenicate using DeviceCode flow
|
||||
sc <- az_rm$new(tenant="{TID}", app="{CID}", auth_type="device")
|
||||
# Manually authenticate using device code flow
|
||||
sc
|
||||
```
|
||||
|
||||
Загрузка…
Ссылка в новой задаче