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 Wert des Parameters |
Fehlerhafte Anfrage | 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 wurde nicht gefunden | Eine Azure-Ressource, auf die in einem Parameterwert verwiesen wird, kann nicht gefunden werden. |
Authentifizierung | Fehler bei der Microsoft Entra-Authentifizierung. |
Der parameter --debug
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 finden Sie Beispiele für --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 Fehlerbehebungsausgabe. 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 Ausgabe des Fehlers --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 für --debug
zur JSON-Formatierung finden Sie unter Unterschiede in der Zitation 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:
"Ungültige Anfrage ... {something} ist ungültig" kann durch ein Leerzeichen, ein- oder doppeltes Anführungszeichen oder einen Mangel an Anführungszeichen verursacht werden.
"Unerwartetes Zeichen..." erscheint, wenn ein zusätzliches Leerzeichen oder Anführungszeichen vorhanden sind.
"Ungültiger jmespath_type Wert" Fehler kommt häufig aus einer falschen Quotierung im
--query
Parameter."Variablenverweis ist ungültig" tritt auf, wenn eine Zeichenfolge aufgrund einer Verkettung oder eines fehlenden Escape-Zeichens nicht ordnungsgemäß formatiert ist.
"Nicht erkannte Argumente" wird häufig durch ein falsches Zeilenfortsetzungszeichen oder einen falsch geschriebenen Parameternamen verursacht.
"Fehlender Ausdruck nach dem 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 in Bash, PowerShell und Cmd Anleitung
- Finden Sie viele
--query
Parameterbeispiele in Abfrage der Azure CLI-Befehlsausgabe mithilfe einer JMESPath-Abfrage- - So verwenden Sie die Azure CLI in der 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 Beispielskript in ACS Bash ausführen können, aber es nicht in Windows PowerShell ausführbar ist, sollten Sie Ihre Verwendung von einfachen und doppelten Anführungszeichen sowie Escapezeichen überprüfen.
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 --output tsv
angeben. Hier ist 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 sind erforderlich oder werden erwartet
Dieser Fehler wird angezeigt, wenn einem Azure CLI-Befehl ein erforderlicher Parameter fehlt, oder es einen typografischen Fehler gibt, der dazu führt, dass die Azure CLI den Verweisbefehlfalsch interpretiert. 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. Derzeit wird Splatting mit Azure CLI-Befehlen nicht 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, hat unsichtbare führende oder nachfolgende Leerzeichen.
- Die Ressource ist vorhanden, befindet sich aber in einem anderen Abonnement.
Fehler: Fehler beim Parsen des Strings 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 @<file>
-Konvention von 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.exefinden Sie unter Quoting-Unterschiede zwischen Skriptsprachen – JSON-Zeichenfolgen Lernprogramm.
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 Fehlerbeispiel für eine VM, die nicht in der westus
-Region 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 z. B. az storage account create
ausführen 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-.
Arbeiten hinter einem Proxy
Wenn Sie Azure CLI über einen Proxyserver verwenden, der selbstsignierte Zertifikate nutzt, könnte die von der Azure CLI verwendete Python-Bibliothek möglicherweise den folgenden Fehler verursachen: SSLError("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)
. Um diesen Fehler zu beheben, legen Sie die Umgebungsvariable REQUESTS_CA_BUNDLE
auf den Pfad der Zertifikatdatei der Zertifizierungsstelle im PEM-Format fest.
Betriebssystem | Standardmäßiges Zertifizierungsstellenbundle |
---|---|
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 | Intel-Modelle: /usr/local/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem Siliziummodelle: /opt/homebrew/Cellar/azure-cli/<cliversion>/libexec/lib/python<version>/site-packages/certifi/cacert.pem |
Fügen Sie das Zertifikat des Proxyservers zur Zertifikatsdatei des CA-Bündels hinzu, oder kopieren Sie den Inhalt in eine andere Zertifikatsdatei. Legen Sie dann REQUESTS_CA_BUNDLE
auf den neuen Dateispeicherort fest. Hier ist ein Beispiel:
<Original cacert.pem>
-----BEGIN CERTIFICATE-----
<Your proxy's certificate here>
-----END CERTIFICATE-----
Für einige Proxys ist eine Authentifizierung erforderlich. Das Format der HTTP_PROXY
- oder HTTPS_PROXY
Umgebungsvariablen sollte die Authentifizierung enthalten, z. B. 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 in der Anleitung Bereinigung und Problembehandlung im Lernprogramm Arbeiten mit Dienstprinzipalen.
Andere Probleme
Wenn ein Produktproblem mit Azure CLI nicht in diesem Artikel aufgeführt ist, melden Sie ein Problem auf GitHub.