title | description | manager | author | ms.author | ms.date | ms.topic | ms.service | ms.tool | ms.custom |
---|---|---|---|---|---|---|---|---|---|
Learn how to use the Azure REST API with Azure CLI| Microsoft Docs |
Learn how to use Azure rest with Azure Command Line (CLI). |
jasongroce |
daphnemamsft |
daphnema |
01/31/2024 |
conceptual |
azure-cli |
azure-cli |
devx-track-azurecli |
Representational State Transfer (REST) APIs
are service endpoints that support different sets of HTTP operations (or methods). These HTTP
methods allow you to perform different actions for your service's resources. The az rest
command
should only be used when an existing Azure CLI command isn't
available.
Upon completion of this article, you will know how to use the PUT, PATCH, GET, POST, and DELETE HTTP requests to manage Azure Container Registry resources. The Azure Container Registry is a managed registry service that allows you to create and maintain Azure container registries that store container images and related artifacts.
[!INCLUDE include]
To invoke a custom Azure REST API request with Azure CLI, use the az rest
command, followed by the --url
parameter. The --url
parameter defines the URL of the requested
resource, and is the only required parameter.
Note
- The
az rest
command automatically authenticates using the logged-in credential. If Authorization header is not set, it attaches headerAuthorization: Bearer <token>
, where<token>
is retrieved from Microsoft Entra ID. The target resource of the token will be derived from the--url
parameter when the--url
parameter starts with an endpoint from the output of theaz cloud show --query endpoints
command. Use the--resource
parameter for a custom resource. - If Content-Type header is not set and
--body
is a valid JSON string, Content-Type header will default to "application/json".
Use the PUT HTTP method to create a new Azure Container Registry.
# Command format example
az rest --method put \
--url https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.ContainerRegistry/registries/<containerRegistryName>?api-version=2023-01-01-preview \
--body "{'location': '<locationName>', 'sku': {'name': '<skuName>'}, 'properties': {'adminUserEnabled': '<propertyValue>'}}"
Here's an example with completed parameters:
# Variable block
let "randomIdentifier=$RANDOM*$RANDOM"
subscriptionId="00000000-0000-0000-0000-000000000000"
resourceGroup="msdocs-app-rg$randomIdentifier"
containerRegistryName="msdocscr$randomIdentifier"
locationName="westus"
skuName="Standard"
propertyValue="true"
# Create resource group
az group create --name $resourceGroup --location $locationName --output json
# Invoke request
az rest --method put \
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview \
--body "{'location': '$locationName', 'sku': {'name': '$skuName'}, 'properties': {'adminUserEnabled': '$propertyValue'}}"
# Variable block
$randomIdentifier = (New-Guid).ToString().Substring(0,8)
$subscriptionId="00000000-0000-0000-0000-000000000000"
$resourceGroup="msdocs-app-rg$randomIdentifier"
$containerRegistryName="msdocscr$randomIdentifier"
$locationName="westus"
$skuName="Standard"
$propertyValue="true"
# Create resource group
az group create --name $resourceGroup --location $locationName --output json
# Invoke request
az rest --method put `
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/${containerRegistryName}?api-version=2023-01-01-preview `
--body "{'location': '$locationName', 'sku': {'name': '$skuName'}, 'properties': {'adminUserEnabled': '$propertyValue'}}"
JSON output for both Bash and Powershell:
{
"id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.ContainerRegistry/registries/<containerRegistryName>",
"location": "<location>",
"name": "<containerRegistryName>",
"properties": {
"adminUserEnabled": true,
"anonymousPullEnabled": false,
"creationDate": "2024-01-03T18:38:36.7089583Z",
"dataEndpointEnabled": false,
"dataEndpointHostNames": [],
"encryption": {
"status": "disabled"
},
"loginServer": "<containerRegistryName>.azurecr.io",
"networkRuleBypassOptions": "AzureServices",
"policies": {
"azureADAuthenticationAsArmPolicy": {
"status": "enabled"
},
"exportPolicy": {
"status": "enabled"
},
"quarantinePolicy": {
"status": "disabled"
},
"retentionPolicy": {
"days": 7,
"lastUpdatedTime": "2024-01-03T19:44:53.9770581+00:00",
"status": "disabled"
},
"softDeletePolicy": {
"lastUpdatedTime": "2024-01-03T19:44:53.9771117+00:00",
"retentionDays": 7,
"status": "disabled"
},
"trustPolicy": {
"status": "disabled",
"type": "Notary"
}
},
"privateEndpointConnections": [],
"provisioningState": "Succeeded",
"publicNetworkAccess": "Enabled",
"zoneRedundancy": "Disabled"
},
"sku": {
"name": "Standard",
"tier": "Standard"
},
"systemData": {
"createdAt": "2024-01-03T18:38:36.7089583+00:00",
"createdBy": "<username>@microsoft.com",
"createdByType": "User",
"lastModifiedAt": "2024-01-03T19:44:53.684342+00:00",
"lastModifiedBy": "<username>@microsoft.com",
"lastModifiedByType": "User"
},
"tags":{},
"type": "Microsoft.ContainerRegistry/registries"
}
You have now successfully created your new Azure Container Registry using az rest
!
Update your Azure Container Registry by using the PATCH HTTP request. Edit the --body
parameter
with the properties you want to update. This example uses the variables set in the previous section,
and updates the SKU name ($skuName="Premium") of the Azure Container Registry.
#Variable Block
$skuName="Premium"
az rest --method patch \
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview \
--body "{'location': '$locationName', 'sku': {'name': '$skuName'}, 'properties': {'adminUserEnabled': '$propertyValue'}}"
In a PowerShell environment, add {}
brackets around the containerRegistryName
variable as a question mark is an allowed character in a variable name.
#Variable Block
$skuName="Premium"
az rest --method patch `
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/${containerRegistryName}?api-version=2023-01-01-preview `
--body "{'location': '$locationName', 'sku': {'name': '$skuName'}, 'properties': {'adminUserEnabled': '$propertyValue'}}"
The following JSON dictionary output has fields omitted for brevity:
{
"id": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.ContainerRegistry/registries/<containerRegistryName>",
"location": "westus",
"name": "<containerRegistryName>",
"properties": {...},
"sku": {
"name": "Premium",
"tier": "Premium"
},
"systemData": {...},
"type": "Microsoft.ContainerRegistry/registries"
}
Use the GET HTTP request see the update results from the PATCH request. This example uses the variables set in the previous section.
az rest --method get \
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview
In a PowerShell environment, add {}
brackets around the containerRegistryName
variable as a
question mark is an allowed character in a variable name.
az rest --method get `
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/${containerRegistryName}?api-version=2023-01-01-preview
The output for GET method is the same as the one shown for PUT.
Use the POST HTTP request to regenerate one of the login credentials for the Azure Container Registry created in this article.
# Variable block
$passwordValue="password"
az rest --method post \
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName/regenerateCredential?api-version=2023-01-01-preview \
--body "{'name': '$passwordValue'}"
# Variable block
$passwordValue="password"
az rest --method post `
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName/regenerateCredential?api-version=2023-01-01-preview `
--body "{'name': '$passwordValue'}"
The following JSON dictionary output has fields omitted for brevity:
{
"passwords": [
{
"name": "password",
"value": "<passwordValue>"
},
{
"name": "password2",
"value": "<passwordValue2>"
}
],
"username": "<containerRegistryName>"
}
After the request is complete, your specified Azure Container Registry credentials will be regenerated with a new password along with your existing password (password2).
Use the DELETE HTTP request to delete an existing Azure Container Registry.
az rest --method delete \
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview
In a PowerShell environment, add {}
brackets around the containerRegistryName
variable as a
question mark is an allowed character in a variable name.
az rest --method delete `
--url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/${containerRegistryName}?api-version=2023-01-01-preview
When you are finished with the resources created in this article, you can delete the resource group. When you delete the resource group, all resources in that resource group are deleted.
az group delete --resource-group <resourceGroupName>