Usar a API REST do Azure com a CLI do Azure

  • Artigo

As APIs REST (Representational State Transfer) são pontos de extremidade de serviço que oferecem suporte a diferentes conjuntos de operações (ou métodos) HTTP. Esses métodos HTTP permitem que você execute diferentes ações para os recursos do seu serviço. O az rest comando só deve ser usado quando um comando existente da CLI do Azure não estiver disponível.

Após a conclusão deste artigo, você saberá como usar as solicitações HTTP PUT, PATCH, GET, POST e DELETE para gerenciar os recursos do Registro de Contêiner do Azure. O Registro de Contêiner do Azure é um serviço de registro gerenciado que permite criar e manter registros de contêiner do Azure que armazenam imagens de contêiner e artefatos relacionados.

Pré-requisitos

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Configure sua solicitação personalizada da API REST do Azure:

Para invocar uma solicitação de API REST do Azure personalizada com a CLI do Azure, use o az rest comando, seguido pelo --url parâmetro. O --url parâmetro define a URL do recurso solicitado e é o único parâmetro necessário.

Nota

  • O az rest comando é autenticado automaticamente usando a credencial conectada. Se o cabeçalho de autorização não estiver definido, ele anexará o cabeçalho Authorization: Bearer <token>, onde <token> é recuperado do ID do Microsoft Entra. O recurso de destino do token será derivado do --url parâmetro quando o --url parâmetro começar com um ponto de extremidade da saída do az cloud show --query endpoints comando. Use o --resource parâmetro para um recurso personalizado.
  • Se o cabeçalho Content-Type não estiver definido e --body for uma cadeia de caracteres JSON válida, o cabeçalho Content-Type assumirá como padrão "application/json".

Usar PUT para criar um Registro de Contêiner do Azure

Use o método HTTP PUT para criar um novo Registro de Contêiner do Azure.

# 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>'}}"

Aqui está um exemplo com parâmetros concluídos:

# 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'}}"

Saída JSON para Bash e 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"
}

Agora você criou com êxito seu novo Registro de Contêiner do Azure usando az rest!

Use PATCH para atualizar seu Registro de Contêiner do Azure

Atualize seu Registro de Contêiner do Azure usando a solicitação HTTP PATCH. Edite o --body parâmetro com as propriedades que você deseja atualizar. Este exemplo usa as variáveis definidas na seção anterior e atualiza o nome da SKU ($skuName="Premium") do Registro de Contêiner do Azure.

#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'}}"

A saída do dicionário JSON a seguir tem campos omitidos para brevidade:

{
  "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 GET para recuperar seu Registro de Contêiner do Azure

Use a solicitação HTTP GET, veja os resultados da atualização da solicitação PATCH. Este exemplo usa as variáveis definidas na seção anterior.

az rest --method get \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

A saída para o método GET é a mesma mostrada para PUT.

Use o POST para regenerar suas credenciais do Registro de Contêiner do Azure

Use a solicitação HTTP POST para regenerar uma das credenciais de logon para o Registro de Contêiner do Azure criado neste artigo.

# 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'}"

A saída do dicionário JSON a seguir tem campos omitidos para brevidade:

{
  "passwords": [
    {
      "name": "password",
      "value": "<passwordValue>"
    },
    {
      "name": "password2",
      "value": "<passwordValue2>"
    }
  ],
  "username": "<containerRegistryName>"
}

Depois que a solicitação for concluída, suas credenciais especificadas do Registro de Contêiner do Azure serão regeneradas com uma nova senha junto com sua senha existente (senha2).

Use DELETE para excluir seu Registro de Contêiner do Azure

Use a solicitação HTTP DELETE para excluir um Registro de Contêiner do Azure existente.

az rest --method delete \
    --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ContainerRegistry/registries/$containerRegistryName?api-version=2023-01-01-preview

Clean up resources (Limpar recursos)

Quando terminar os recursos criados neste artigo, você poderá excluir o grupo de recursos. Quando você exclui o grupo de recursos, todos os recursos desse grupo de recursos são excluídos.

az group delete --resource-group <resourceGroupName>