Quickstart: Create, assign, and run a storage task by using Azure CLI

In this quickstart, you learn how to use Azure CLI to create a storage task and assign it to an Azure Storage account. Then, you'll review the results of the run. The storage task applies a time-based immutability policy any Microsoft Word documents that exist in the storage account.

Prerequisites

• An Azure subscription. See create an account for free.

• An Azure storage account. See create a storage account. As you create the account, make sure to enable version-level immutability support and that you don't enable the hierarchical namespace feature.

  During the public, you can target only storage accounts that are in the same region as the storage tasks.

• The Storage Blob Data Owner role is assigned to your user identity in the context of the storage account or resource group.

• A custom role assigned to your user identity in the context of the resource group which contains the RBAC actions necessary to assign a task to a storage account. See Permissions required to assign a task.

Prepare your environment for the Azure CLI

• Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

• This article requires version 2.57.0 or later of the Azure CLI. If using Azure Cloud Shell, the latest version is already installed.

Sign in to your Azure account

1. Sign in to your Azure account with the az login command.

   az login
   

   If the CLI can open your default browser, it will do so and load an Azure sign-in page.

   Otherwise, open a browser page at https://aka.ms/devicelogin and enter the authorization code displayed in your terminal. Then, sign in with your account credentials in the browser.

2. If your identity is associated with more than one subscription, and you aren't prompted to select the subscription, then set your active subscription to subscription of the storage account that you want operate upon. In this example, replace the <subscription-id> placeholder value with the ID of your subscription.

   az account set --subscription <subscription-id>
   

Create a storage task

1. Define a condition by using JSON. A condition a collection of one or more clauses. Each clause contains a property, a value, and an operator. In the following JSON, the property is Name, the value is .docx, and the operator is endsWith. This clause allows operations only on Microsoft Word documents. To learn more about the structure of conditions and a complete list of properties and operators, see Storage task conditions.

   conditionclause="[[endsWith(Name,'/.docx'/)]]"
   

Note

Azure CLI uses shorthand syntax. Shorthand syntax is a simplified representation of a JSON string. To learn more, see How to use shorthand syntax with Azure CLI.

2. Define each operation. The following example defines an operation that sets an immutability policy, and an operation that sets a blob index tag in the metadata of a Word document.

   policyoperation="{name:'SetBlobImmutabilityPolicy',parameters:{untilDate:'2024-10-20T22:30:40',mode:'locked'},onSuccess:'continue',onFailure:'break'}"
   tagoperation="{name:'SetBlobTags',parameters:{'tagsetImmutabilityUpdatedBy':'StorageTaskQuickstart'},onSuccess:'continue',onFailure:'break'}"
   action="{if:{condition:'"${conditionclause}"',operations:/["${policyoperation}","${tagoperation}"]}}"
   

3. Create a storage task by using the az storage-actions task create command, and pass in the conditions and operations that you defined earlier. This example creates a storage task named mystoragetask in resource group mystoragetaskresourcegroup in the West US region.

   az storage-actions task create \
      -g mystoragetaskresourcegroup \
      -n mystoragetask \
      --identity "{type:SystemAssigned}" \ 
      --action "{if:{condition:'"${conditionclause}"',operations:["${policyoperation}","${tagoperation}"]}}" \
      --description "My storage task" --enabled true
   

Add an assignment

A storage task assignment specifies a storage account. After you enable the storage task, the conditions and operations of your task will be applied to that storage account. The assignment also contains configuration properties which help you target specific blobs, or specify when and how often the task runs. You can add an assignment for each account you want to target.

1. Create a storage task assignment by using the az storage account task-assignment create command. The following assignment targets the mycontainer container of an account named mystorageaccount. This assignment specifies that the task will run only one time, and will save execution reports to a folder named storage-tasks-report. The task is scheduled to run 10 minutes from the present time.

   id=$(az storage-actions task show -g mystoragetaskresourcegroup -n mystoragetask --query "id") 
   current_datetime=$(date +"%Y-%m-%dT%H:%M:%S")
   executioncontextvariable="{target:{prefix:[mycontainer/],excludePrefix:[]},trigger:{type:'RunOnce',parameters:{startOn:'"${current_datetime}"'}}}"
   
   az storage account task-assignment create \
      -g mystoragetaskresourcegroup \
      -n mystoragetaskassignment \
      --account-name mystorageaccount \
      --description 'My Storage task assignment' \
      --enabled false \
      --task-id $id \
      --execution-context $executioncontextvariable \
      --report "{prefix:storage-tasks-report}"
   

2. Give the storage task permission to perform operations on the target storage account. Assign the role of Storage Blob Data Owner to the system-assigned managed identity of the storage task.

   $roleDefinitionId="b7e6dc6d-f1e8-4753-8033-0f276bb0955b" \
   $principalID=az storage-actions task show -g mystoragetaskresourcegroup -n mystoragetask --query "identity.principalId"
   $storageAccountID=az storage account show --name mystorageaccount --resource-group mystoragetaskresourcegroup --query "id"
   
   az role assignment create \
      --assignee-object-id $principalID \
      --scope $storageAccountID \
      --role $roleDefinitionId \
      --description "My role assignment" 
   

View the results of a task run

After the task completes running, get a run report summary for each assignment by using the blah command.

az storage account task-assignment list-report \
   --account-name mystorageaccount \
   --resource-group mystoragetaskresourcegroup \
   --name mystoragetaskassignment

The SummaryReportPath field of each report summary contains a path to a detailed report. That report contains comma-separated list of the container, the blob, and the operation performed along with a status.

Clean up resources

Remove all of the assets you've created. The easiest way to remove the assets is to delete the resource group. Removing the resource group also deletes all resources included within the group. In the following example, removing the resource group removes the storage account and the resource group itself.

az group delete \
   --name <resource-group> \
   --no-wait

Next steps

Create a storage task