Verwenden der Azure REST-API mit Azure CLI

  • Artikel

REST-APIs (Representational State Transfer) sind Dienstendpunkte, die unterschiedliche Sätze von HTTP-Vorgängen (oder Methoden) unterstützen. Mit diesen HTTP-Methoden können Sie verschiedene Aktionen für die Ressourcen Ihres Diensts ausführen. Der az rest Befehl sollte nur verwendet werden, wenn kein vorhandener Azure CLI-Befehl verfügbar ist.

Nach Abschluss dieses Artikels wissen Sie, wie Sie die PUT-, PATCH-, GET-, POST- und DELETE-HTTP-Anforderungen zum Verwalten von Azure Container Registry-Ressourcen verwenden. Die Azure Container-Registrierung ist ein verwalteter Registrierungsdienst, mit dem Sie Azure-Containerregistrierungen erstellen und Standard, die Containerimages und zugehörige Artefakte speichern.

Voraussetzungen

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Richten Sie Ihre benutzerdefinierte Azure REST-API-Anforderung ein:

Um eine benutzerdefinierte Azure REST-API-Anforderung mit Azure CLI aufzurufen, verwenden Sie den az rest Befehl, gefolgt vom --url Parameter. Der --url Parameter definiert die URL der angeforderten Ressource und ist der einzige erforderliche Parameter.

Hinweis

  • Der az rest Befehl authentifiziert sich automatisch mit den angemeldeten Anmeldeinformationen. Wenn kein Autorisierungsheader festgelegt ist, wird der Header Authorization: Bearer <token>angefügt, der <token> von der Microsoft Entra-ID abgerufen wird. Die Zielressource des Tokens wird vom --url Parameter abgeleitet, wenn der --url Parameter mit einem Endpunkt aus der Ausgabe des az cloud show --query endpoints Befehls beginnt. Verwenden Sie den --resource Parameter für eine benutzerdefinierte Ressource.
  • Wenn der Content-Type-Header nicht festgelegt ist und --body eine gültige JSON-Zeichenfolge ist, wird der Content-Type-Header standardmäßig auf "application/json" festgelegt.

Verwenden von PUT zum Erstellen einer Azure-Containerregistrierung

Verwenden Sie die PUT-HTTP-Methode, um eine neue Azure-Containerregistrierung zu erstellen.

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

Hier ist ein Beispiel mit abgeschlossenen Parametern:

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

JSON-Ausgabe für Bash und 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"
}

Sie haben jetzt erfolgreich Ihre neue Azure Container Registry mit az rest!

Verwenden von PATCH zum Aktualisieren Der Azure-Containerregistrierung

Aktualisieren Sie Ihre Azure-Containerregistrierung mithilfe der PATCH-HTTP-Anforderung. Bearbeiten Sie den --body Parameter mit den Eigenschaften, die Sie aktualisieren möchten. In diesem Beispiel werden die im vorherigen Abschnitt festgelegten Variablen verwendet und der SKU-Name ($skuName="Premium") der Azure-Containerregistrierung aktualisiert.

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

Die folgende JSON-Wörterbuchausgabe enthält Felder, die aus Platzgründen weggelassen werden:

{
  "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"
}

Verwenden von GET zum Abrufen Ihrer Azure-Containerregistrierung

Verwenden Sie die GET-HTTP-Anforderung, um die Updateergebnisse aus der PATCH-Anforderung anzuzeigen. In diesem Beispiel werden die im vorherigen Abschnitt festgelegten Variablen verwendet.

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

Die Ausgabe für DIE GET-Methode entspricht der für PUT angezeigten Methode.

Verwenden von POST zum Erneuten Generieren Ihrer Azure Container-Registrierungsanmeldeinformationen

Verwenden Sie die POST-HTTP-Anforderung, um eine der Anmeldeinformationen für die in diesem Artikel erstellte Azure-Containerregistrierung neu zu generieren.

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

Die folgende JSON-Wörterbuchausgabe enthält Felder, die aus Platzgründen weggelassen werden:

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

Nachdem die Anforderung abgeschlossen ist, werden Ihre angegebenen Azure Container Registry-Anmeldeinformationen zusammen mit Ihrem vorhandenen Kennwort (Kennwort2) neu generiert.

Verwenden von DELETE zum Löschen Ihrer Azure-Containerregistrierung

Verwenden Sie die DELETE-HTTP-Anforderung, um eine vorhandene Azure Container-Registrierung zu löschen.

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

Bereinigen von Ressourcen

Wenn Sie mit den in diesem Artikel erstellten Ressourcen fertig sind, können Sie die Ressourcengruppe löschen. Wenn Sie die Ressourcengruppe löschen, werden alle Ressourcen in dieser Ressourcengruppe gelöscht.

az group delete --resource-group <resourceGroupName>