Problembehandlung bei Azure CLI
Fehlerkategorien
Die meisten fehler, die von der Azure CLI zurückgegeben werden, fallen in eine der folgenden Kategorien:
Fehlerkategorie | Allgemeine Fehlerursache |
---|---|
Nicht erkanntes Argument | Ein Parameter ist falsch geschrieben oder nicht vorhanden. |
Erforderliches Argument fehlt | Ein erforderlicher Parameter wird nicht angegeben, oder es wird nur eins von zwei "Parameterpaaren" angegeben. Ein Parameter kann auch falsch geschrieben werden. |
Sich gegenseitig ausschließende Argumente | Zwei oder mehr Parameter können nicht zusammen angegeben werden. |
Ungültiger Argumentwert | Der Parameterwert ist ungültig. Dieser Fehler liegt häufig an der Quotierung, einem Escapezeichen oder Abstand. |
Ungültige Anforderung | Dieser Fehler wird durch einen HTTP-Statuscode von 400 zurückgegeben. Suchen Sie nach fehlendem Leerzeichen, fehlendem Parameterstrich oder einem zusätzlichen oder fehlenden einfachen oder doppelten Anführungszeichen. Dieser Fehler tritt auch auf, wenn ein Parameterwert keinen zulässigen Wert enthält. |
Ressource nicht gefunden | Eine Azure-Ressource, auf die in einem Parameterwert verwiesen wird, kann nicht gefunden werden. |
Authentifizierung | Fehler bei der Microsoft Entra-Authentifizierung. |
Der --debug
Parameter
Eine der besten Methoden, um zu sehen, was die Azure CLI für jeden Azure CLI-Referenzbefehl ausführt, besteht darin, den --debug
Parameter zu verwenden. Hier sind Beispiele --debug
für einen fehlgeschlagenen und erfolgreichen Befehl:
# Error example: Create a resource group, but omit the quotes around the resource group name.
az group create --location eastus2 --name msdocs-rg-test --debug
Hier ist ein Teil der Debugausgabe. Beachten Sie den Protokollspeicherort und das nicht erkannte Argument.
cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-name', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.azclierror: unrecognized arguments: msdocs-rg-test
...
Vergleichen Sie die oben angegebene Fehlerausgabe --debug
mit einer erfolgreichen Ausführung:
# Correct example: Because the resource group name contains special characters, enclose it in quotes
az group create --location eastus2 --name "msdocs-rg-test" --debug
Hier ist ein Teil der Debugausgabe. Beachten Sie den Protokollspeicherort, den API-Aufruf und die Laufzeit.
cli.knack.cli: Command arguments: ['group', 'create', '-l', 'eastus2', '-n', 'msdocs-rg-test', '--debug']
...
cli.azure.cli.core.azlogging: metadata file logging enabled - writing logs to '/home/myName/.azure/commands/YYYY-MM-DD.HH-MM-SS.group_create.8912.log'.
...
cli.azure.cli.core.sdk.policies: Request URL: 'https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/msdocs-rg-test?api-version=YYYY-MM-DD'
cli.azure.cli.core.sdk.policies: Request method: 'PUT'
cli.azure.cli.core.sdk.policies: Request headers:
cli.azure.cli.core.sdk.policies: 'Content-Type': 'application/json'
cli.azure.cli.core.sdk.policies: 'Content-Length': '23'
cli.azure.cli.core.sdk.policies: 'Accept': 'application/json'
cli.azure.cli.core.sdk.policies: 'x-ms-client-request-id': 'ba7ee6f4-2dcc-11ef-81ce-00155dadc5c8'
cli.azure.cli.core.sdk.policies: 'CommandName': 'group create'
cli.azure.cli.core.sdk.policies: 'ParameterSetName': '-l -n --debug'
cli.azure.cli.core.sdk.policies: 'User-Agent': 'AZURECLI/2.61.0 (RPM) azsdk-python-core/1.28.0 Python/3.9.19 (Linux-5.10.102.2-microsoft-standard-x86_64-with-glibc2.35) cloud-shell/1.0'
cli.azure.cli.core.sdk.policies: 'Authorization': '*****'
cli.azure.cli.core.sdk.policies: Request body:
cli.azure.cli.core.sdk.policies: {"location": "eastus2"}
urllib3.connectionpool: Starting new HTTPS connection (1): management.azure.com:443
urllib3.connectionpool: https://management.azure.com:443 "PUT /subscriptions/3618afcd-ea52-4ceb-bb46-53bb962d4e0b/resourcegroups/msdocs-rg-test?api-version=2022-09-01 HTTP/1.1" 201 226
cli.azure.cli.core.sdk.policies: Response status: 201
...
cli.azure.cli.core.sdk.policies: 'Date': 'Tue, 18 Jun 2024 23:44:41 GMT'
cli.azure.cli.core.sdk.policies: Response content:
cli.azure.cli.core.sdk.policies: {"id":"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-rg-test","name":"msdocs-rg-test","type":"Microsoft.Resources/resourceGroups","location":"eastus2","properties":{"provisioningState":"Succeeded"}}
...
cli.__main__: Command ran in 1.829 seconds (init: 0.111, invoke: 1.718)
Beispiele --debug
für DIE JSON-Formatierung finden Sie unter Quoting-Unterschiede zwischen Skriptsprachen – JSON-Zeichenfolgen.
Häufige Syntaxfehler
Obwohl die Azure CLI sowohl in Bash als auch in PowerShell und Windows Cmd ausgeführt werden kann, gibt es Syntaxunterschiede zwischen Skriptsprachen. Azure CLI-Skripts mit einfachen Anführungszeichen, doppelten Anführungszeichen und Escapezeichen müssen in der Regel geändert werden, wenn sie zwischen Sprachen kopiert werden. Diese Herausforderung zeigt sich am häufigsten in Parameterwerten, insbesondere in Werten, die dem --query
Parameter zugewiesen sind. Nachfolgend finden Sie einige häufige Fehlermeldungen:
"Schlechte Anfrage ... {something} ist ungültig" kann durch ein Leerzeichen, ein- oder doppeltes Anführungszeichen oder einen Mangel an Anführungszeichen verursacht werden.
"Unerwartetes Token..." wird angezeigt, wenn ein zusätzliches Leerzeichen oder Anführungszeichen vorhanden ist.
Fehler "Ungültiger jmespath_type Wert" kommt häufig aus einer falschen Quotierung im
--query
Parameter."Variable reference is not valid" is received when a string isn't formatted properly often due to concatenation or a missing escape character.
"Nicht erkannte Argumente" wird häufig durch ein falsches Zeilenfortsetzungszeichen oder falsch geschriebenen Parameternamen verursacht.
"Fehlender Ausdruck nach einem unären Operator" wird angezeigt, wenn ein Zeilenfortsetzungszeichen fehlt.
Es gibt mehrere Azure CLI-Artikel, die sich mit der Erläuterung von Syntaxfehlern und dem Bereitstellen von Arbeitsbeispielen beschäftigen:
- Quotieren von Unterschieden zwischen Skriptsprachen
- Syntaxunterschiede im Lernprogramm bash, PowerShell und Cmd
- Hier finden Sie viele
--query
Parameterbeispiele in der Azure CLI-Befehlsausgabe mit einer JMESPath-Abfrage. - Verwendung der Azure CLI in einer Bash-Skriptsprache
- Überlegungen zum Ausführen der Azure CLI in einer PowerShell-Skriptsprache
Tipp
Wenn Sie einen Befehlsfehler nicht beheben können, versuchen Sie, eine andere Skriptsprache zu verwenden. Die meisten Azure CLI-Dokumentationen werden in Azure Cloud Shell (ACS) mit einer Bash-Skriptsprache geschrieben und getestet. Wenn Sie ein Artikelbeispiel für die Ausführung in ACS Bash abrufen können, aber nicht in Windows PowerShell ausgeführt werden, überprüfen Sie die Verwendung einzelner und doppelter Anführungszeichen und Escapezeichen.
Fehler: Ungültiger Wert oder nicht vorhanden
Diese Fehler treten häufig auf, wenn Sie versuchen, einen Variablenwert zu verwenden, der ein falsches Format enthält. Die Standardausgabe für Azure CLI ist JSON. Wenn Sie also versuchen, eine ID für eine Azure-Ressource in einer Variablen zu speichern, müssen Sie angeben --output tsv
. Ein Beispiel:
# Get a subscription that contains a name or phrase
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id")
echo $subscriptionID
# output as JSON
[ "00000000-0000-0000-0000-000000000000" ]
# Try to set your subscription to the new ID
az account set --subscription $subscriptionID
# error output
The subscription of '"00000000-0000-0000-0000-000000000000"' doesn't exist in cloud 'AzureCloud'.
Verwenden Sie nun den tsv
Ausgabetyp.
# Get the active subscription
subscriptionID=$(az account list --query "[?contains(name,'my case sensitive search phrase')].id" --output tsv)
echo $subscriptionID
# output as TSV
00000000-0000-0000-0000-000000000000
# Successfully set your subscription to the new ID
az account set --subscription $subscriptionID
Fehler: Argumente werden erwartet oder erforderlich
Dieser Fehler wird angezeigt, wenn ein Azure CLI-Befehl einen erforderlichen Parameter fehlt, oder es gibt einen typografischen Fehler, der dazu führt, dass die Azure CLI den Verweisbefehl falsch analysiert. Wenn Sie mit einem Skript arbeiten, erhalten Sie auch diesen Fehler, wenn eine oder mehrere Bedingungen erfüllt sind:
- Ein Zeilenfortsetzungszeichen fehlt oder ist falsch.
- Beim Arbeiten in der PowerShell-Skriptsprache ist auf der rechten Seite eines Zeilenfortsetzungszeichens ein nachgestelltes Leerzeichen vorhanden. Zurzeit wird splatting nicht mit Azure CLI-Befehlen unterstützt.
- Ein Variablenname enthält ein Sonderzeichen, z. B. einen Gedankenstrich (-).
Fehler: Ressource nicht gefunden
Wenn die Azure CLI den Ressourcennamen oder die ID, die in einem Parameterwert übergeben wird, nicht finden kann, liegt dies in der Regel aus einem der folgenden Gründe:
- Der Ressourcenname oder die ID ist falsch geschrieben.
- Der Ressourcenname enthält Sonderzeichen und ist nicht von einfachen oder doppelten Anführungszeichen umgeben.
- Der Wert, der an eine Variable übergeben wird, weist führende oder nachfolgende Leerzeichen auf.
- Die Ressource ist vorhanden, befindet sich aber in einem anderen Abonnement.
Fehler: Fehler beim Analysieren der Zeichenfolge als JSON
Es gibt Unterschiede zwischen Bash, PowerShell in Linux und PowerShell in Windows. Darüber hinaus können unterschiedliche Versionen von PowerShell unterschiedliche Ergebnisse erzielen. Bei komplexen Parametern wie einer JSON-Zeichenfolge empfiehlt es sich, die Konvention der @<file>
Azure CLI zu verwenden, um die Interpretation einer Shell zu umgehen. Weitere Informationen finden Sie in einem der folgenden Artikel:
Beispiele für JSON-Syntax für Bash, PowerShell und Cmd.exe finden Sie unter Quoting-Unterschiede zwischen Skriptsprachen – Lernprogramm für JSON-Zeichenfolgen .
Fehler: InvalidTemplateDeployment
Wenn Sie versuchen, eine Azure-Ressource an einem Speicherort zu erstellen, der diese Ressource nicht anbietet, wird eine Fehlermeldung angezeigt, die dieser Meldung ähnelt: "Die folgenden SKUs sind für Kapazitätsbeschränkungen fehlgeschlagen: myDesiredSkuName" ist derzeit nicht am Speicherort "mySpecifiedLocation" verfügbar."
Hier ist ein vollständiges Fehlerbeispiel für einen virtuellen Computer, der westus
nicht am Speicherort erstellt werden kann:
{"error":{"code":"InvalidTemplateDeployment","message":"The template deployment 'vm_deploy_<32 character ID>'
is not valid according to the validation procedure. The tracking id is '<36 character ID>'.
See inner errors for details.","details":[{"code":"SkuNotAvailable","message":"The requested VM size for resource
'Following SKUs have failed for Capacity Restrictions: Standard_DS1_v2' is currently not available
in location 'westus'. Please try another size or deploy to a different location
or different zone. See https://aka.ms/azureskunotavailable for details."}]}}
Die Lösung besteht darin, eine Eigenschaft Ihrer angeforderten Azure-Ressource zu ändern oder einen anderen Speicherort zu versuchen.
Fehler: Abonnement nicht gefunden
Wenn Sie einen Abonnementnamen oder eine ID nicht falsch eingegeben haben, tritt dieser Fehler auf, wenn ein Ressourcenanbieter nicht im aktiven Abonnement registriert ist. Wenn Sie beispielsweise ausführen az storage account create
möchten, muss der Microsoft.Storage
Anbieter registriert sein. Informationen zum Registrieren eines Ressourcenanbieters finden Sie unter Azure-Ressourcenanbieter und -Typen.
Fehler: Schlechter Handshake... Fehler bei der Zertifikatüberprüfung.
Informationen zum Beheben dieses Fehlers finden Sie unter "Arbeiten hinter einem Proxy ".
Verwendung hinter einem Proxy
Wenn Sie Azure CLI über einen Proxyserver verwenden, der selbstsignierte Zertifikate verwendet, kann die python-Anforderungsbibliothek, die von der Azure CLI verwendet wird, den folgenden Fehler verursachen: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)
Legen Sie zur Behebung dieses Fehlers die Umgebungsvariable REQUESTS_CA_BUNDLE
auf den Pfad der CA-Bundlezertifikatdatei im PEM-Format fest.
Betriebssystem | Standardbundle der Zertifizierungsstelle |
---|---|
Windows 32-Bit | C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
Windows (64-Bit) | C:\Program Files\Microsoft SDKs\Azure\CLI2\Lib\site-packages\certifi\cacert.pem |
Ubuntu/Debian Linux | /opt/az/lib/python<version>/site-packages/certifi/cacert.pem |
CentOS Stream/RHEL/SUSE Linux | /usr/lib64/az/lib/python<version>/site-packages/certifi/cacert.pem |
macOS | /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem |
Fügen Sie das Zertifikat des Proxyservers an die CA-Bundlezertifikatdatei an, oder kopieren Sie den Inhalt in eine andere Zertifikatdatei. Legen Sie dann REQUESTS_CA_BUNDLE
auf den neuen Dateispeicherort fest. Hier sehen Sie ein Beispiel:
<Original cacert.pem>
-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----
Einige Proxys erfordern eine Authentifizierung. Das Format der Umgebungsvariablen HTTP_PROXY
oder HTTPS_PROXY
sollte die Authentifizierung beinhalten, etwa HTTPS_PROXY="https://username:password@proxy-server:port"
. Ausführliche Informationen finden Sie unter Konfigurieren von Proxys für das Azure SDK für Python.
Dienstprinzipale
Informationen zur Problembehandlung von Dienstprinzipalen finden Sie im Lernprogramm "Arbeiten mit Dienstprinzipalen" unter "Bereinigen und Problembehandlung".
Andere Probleme
Wenn ein Produktproblem mit Azure CLI in diesem Artikel nicht aufgeführt ist, geben Sie ein Problem auf GitHub an.