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.

In diesem Artikel werden die PUT-, PATCH-, GET-, POST- und DELETE-HTTP-Anforderungen zum Verwalten von Azure Container Registry-Ressourcen veranschaulicht. Die Azure Container Registry ist ein verwalteter Registrierungsdienst, mit dem Sie Azure-Containerregistrierungen erstellen und verwalten können, 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.

Tipps für die Verwendung az rest

Hier sind einige hilfreiche Informationen beim Arbeiten mit az rest:

  • 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. Der --url parameter erforderlich.
  • 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.
  • Stellen Sie bei Verwendung --uri-parameters für Anforderungen in Form von OData sicher, dass sie in verschiedenen Umgebungen escapen $ : in Bash, escape $ as \$ and in , escape as and in PowerShell, escape $ as `$.

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

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

Zusätzliches az rest Beispiel für Microsoft Graph

Manchmal hilft es, ein Beispiel für ein anderes Szenario zu sehen. Hier ist also ein Beispiel, das die Microsoft Graph-API verwendet. Rufen Sie zum Aktualisieren von Umleitungs-URIs für eine Anwendung die REST-API zum Aktualisieren der Anwendung auf, wie in diesem Code gezeigt:

# Get the application
az rest --method GET \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001'

# Update `redirectUris` for `web` property
az rest --method PATCH \
    --uri 'https://graph.microsoft.com/v1.0/applications/b4e4d2ab-e2cb-45d5-a31a-98eb3f364001' \
    --body '{"web":{"redirectUris":["https://myapp.com"]}}'

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>

Weitere Informationen