az_resource {AzureRMR}

Azure resource class

Description

Class representing a generic Azure resource.

Format

An R6 object of class az_resource.

Methods

• new(...): Initialize a new resource object. See 'Initialization' for more details.

• 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(): Synchronise the R object with the resource it represents in Azure. Returns the properties$provisioningState field, so you can query this programmatically to check if a resource has finished provisioning. Not all resource types require explicit provisioning, in which case this method will return NULL.

• set_api_version(api_version, stable_only=TRUE): Set the API version to use when interacting with the host. If api_version is not supplied, use the latest version available, either the latest stable version (if stable_only=TRUE) or the latest preview version (if stable_only=FALSE).

• get_api_version(): Get the current API version.

• get_subresource(type, name): Get a sub-resource of this resource. See 'Sub-resources' below.

• create_subresource(type, name, ...): Create a sub-resource of this resource.

• delete_subresource(type, name, confirm=TRUE): Delete a sub-resource of this resource.

• do_operation(...): Carry out an operation. See 'Operations' for more details.

• set_tags(..., keep_existing=TRUE): Set the tags on this resource. The tags can be either names or name-value pairs. To delete a tag, set it to NULL.

• get_tags(): Get the tags on this resource.

• create_lock(name, level): Create a management lock on this resource.

• get_lock(name): Returns a management lock object.

• delete_lock(name): Deletes a management lock object.

• list_locks(): List all locks that apply to this resource. Note this includes locks created at the subscription or resource group level.

• add_role_assignment(name, ...): Adds a new role assignment. See 'Role-based access control' below.

• get_role_assignment(id): Retrieves an existing role assignment.

• remove_role_assignment(id): Removes an existing role assignment.

• list_role_assignments(): Lists role assignments.

• get_role_definition(id): Retrieves an existing role definition.

• list_role_definitions() Lists role definitions.

Initialization

There are multiple ways to initialize a new resource object. The new() method can retrieve an existing resource, deploy/create a new resource, or create an empty/null object (without communicating with the host), based on the arguments you supply.

All of these initialization options have the following arguments in common.

1. token: An OAuth 2.0 token, as generated by get_azure_token.

2. subscription: The subscription ID.

3. api_version: Optionally, the API version to use when interacting with the host. By default, this is NULL in which case the latest API version will be used.

4. A set of identifying arguments:

   • resource_group: The resource group containing the resource.

   • id: The full ID of the resource. This is a string of the form ⁠/subscriptions/{uuid}/resourceGroups/{resource-group-name}/provider/{resource-provider-name}/{resource-path}/{resource-name}⁠.

   • provider: The provider of the resource, eg Microsoft.Compute.

   • path: The 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 id will fill in the values for all the other identifying arguments. Similarly, providing type will fill in the values for provider and path. Unless you provide id, you must also provide name.

The default behaviour for new() is to retrieve an existing resource, which occurs if you supply only the arguments listed above. If you also supply an argument deployed_properties=NULL, this will create a null object. If you supply any other (named) arguments, new() will create a new object on the host, with the supplied arguments as parameters.

Generally, the easiest way to initialize an object is via the get_resource, create_resource or list_resources methods of the az_resource_group class, which will handle all the gory details automatically.

Operations

The do_operation() method allows you to carry out arbitrary operations on the resource. It takes the following arguments:

• 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 PUT, POST or PATCH request.

• http_verb: The HTTP verb as a string, one of GET, PUT, POST, DELETE, HEAD or PATCH.

Consult the Azure documentation for your resource to find out what operations are supported.

Sub-resources

Some resource types can have sub-resources: objects exposed by Resource Manager that make up a part of their parent's functionality. For example, a storage account (type Microsoft.Storage/storageAccounts) provides the blob storage service, which can be accessed via Resource Manager as a sub-resource of type Microsoft.Storage/storageAccounts/blobServices/default.

To retrieve an existing sub-resource, use the get_subresource() method. You do not need to include the parent resource's type and name. For example, if res is a resource for a storage account, and you want to retrieve the sub-resource for the blob container "myblobs", call

res$get_subresource(type="blobServices/default/containers", name="myblobs")

Notice that the storage account's resource type and name are omitted from the get_subresource arguments. Similarly, to create a new subresource, call the create_subresource() method with the same naming convention, passing any required fields as named arguments; and to delete it, call delete_subresource().

Role-based access control

AzureRMR implements a subset of the full RBAC functionality within Azure Active Directory. You can retrieve role definitions and add and remove role assignments, at the subscription, resource group and resource levels. See rbac for more information.

See Also

az_resource_group, call_azure_rm, call_azure_url, Resources API reference

For role-based access control methods, see rbac

For management locks, see lock

Examples

## Not run: 

# recommended way to retrieve a resource: via a resource group object
# storage account:
stor <- resgroup$get_resource(type="Microsoft.Storage/storageAccounts", name="mystorage")
# virtual machine:
vm <- resgroup$get_resource(type="Microsoft.Compute/virtualMachines", name="myvm")

## carry out operations on a resource

# storage account: get access keys
stor$do_operation("listKeys", http_verb="POST")

# virtual machine: run a script
vm$do_operation("runCommand",
    body=list(
        commandId="RunShellScript", # RunPowerShellScript for Windows
        script=as.list("ifconfig > /tmp/ifconfig.out")
    ),
    encode="json",
    http_verb="POST")

## retrieve properties

# storage account: endpoint URIs
stor$properties$primaryEndpoints$file
stor$properties$primaryEndpoints$blob

# virtual machine: hardware profile
vm$properties$hardwareProfile

## update a resource: resizing a VM
properties <- list(hardwareProfile=list(vmSize="Standard_DS3_v2"))
vm$do_operation(http_verb="PATCH",
    body=list(properties=properties),
    encode="json")

# sync with Azure: useful to track resource creation/update status
vm$sync_fields()

## subresource: create a public blob container
stor$create_subresource(type="blobservices/default/containers", name="mycontainer",
    properties=list(publicAccess="container"))

## delete a subresource and resource
stor$delete_subresource(type="blobservices/default/containers", name="mycontainer")
stor$delete()


## End(Not run)