NAME
gdcloud topic command-conventions – Zusätzliche Hilfe zu gdcloud-Befehlskonventionen.
BESCHREIBUNG
Das Design der gcloud CLI-Befehle folgt einer Reihe von gemeinsamen Prinzipien und Konventionen. In diesem Dokument werden sie ausführlich beschrieben.
Konventionen sind eher Ziele als Regeln. Informationen zu Ausnahmen finden Sie in der Dokumentation zu den einzelnen Befehlen, wenn Sie das Flag --help verwenden.
BEFEHLSHIERARCHIE
gdcloud CLI-Befehle sind als Baum organisiert, wobei „gdcloud“ die Wurzel, Befehlsgruppen die inneren Knoten und Befehle die Blattknoten sind. Gruppenbefehle sind ausführbar, aber nur zum Anzeigen des Hilfetexts.
Alle Gruppen und Befehle haben das Flag --help, mit dem der Hilfetext als Standardausgabe angezeigt wird. Der Hilfetext wird aus der ausgeführten ausführbaren Datei abgeleitet und ist daher immer aktuell, auch wenn Sie zwischen mehreren Release-Installationen wechseln.
BEFEHLSZEILE
Alle gdcloud-Befehle haben dieselbe Form.
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Flag- und Positionsargumente können gemischt werden. Aus Gründen der Konsistenz werden Positionsargumente jedoch normalerweise zuerst in der Reihenfolge und dann Flags in beliebiger Reihenfolge angezeigt.
NOTATION FÜR DIE BEFEHLSNUTZUNG
Die Befehlsnutzung ist eine Kurzschreibweise, die den vollständigen Befehlsnamen, die Positionsargumente und die Flag-Argumente in gruppierter Reihenfolge enthält. Optionale Argumente sind in [ ... ] eingeschlossen. Beispiel:
gdcloud foo bar NAME [--format=FORMAT]
So wird der Befehl gdcloud foo bar mit einem erforderlichen Positionsargument NAME, einem optionalen Positionsargument EXTRA und einem optionalen Flag-Argument --format verwendet.
Positionsargumente
Positionsargumente sind geordnet und müssen in der Reihenfolge angegeben werden, die in der Liste der Argumentdefinitionen in der Befehlsnutzung und im Hilfedokument aufgeführt ist.
Flag-Argumente
Flag-Namen werden in Kleinbuchstaben mit dem Präfix -- geschrieben. Bei Flags mit mehreren Wörtern wird - (Bindestrich/Strich) als Worttrennzeichen verwendet.
Gemäß der UNIX-Konvention wird bei Wiederholung eines Flags in der Befehlszeile nur das Flag ganz rechts berücksichtigt. Es wird keine Diagnose ausgegeben. So können Sie ganz einfach Befehlsaliase und Wrapper-Skripts einrichten, die Standardflag-Werte bereitstellen. Diese Werte lassen sich einfach überschreiben, indem Sie sie in der Befehlszeile des Alias oder Wrapper-Skripts angeben.
Boolesche Flags
Viele boolesche Flags haben den impliziten Wert false, einige sind standardmäßig true. Wenn --flag vorhanden ist, wird das Flag auf true oder false gesetzt, je nach dem Wert, der durch den Namen des Flags impliziert wird.
Bewertete Flags
Nicht boolesche Flags haben einen expliziten Wert. Der Wert kann angegeben werden, indem er als nächstes Argument nach dem Flag --flag value platziert wird.
Wenn der Wert eine Ganzzahl ist, muss er mindestens 0 sein. Negative Ganzzahlen werden nicht akzeptiert.
Ausgabe
Die Standardausgabe enthält explizite Informationen, die vom Befehl angefordert werden.
Je nach Kontext gibt es möglicherweise Garantien für das Ausgabeformat, um das deterministische Parsen zu unterstützen. Bestimmte Befehle geben Ressourcen zurück. Diese Ressourcen werden in der Regel als Standardausgabe in einem befehlsspezifischen Tabellenformat oder im Standard-YAML-Format aufgeführt. Außerdem kann das Flag --format verwendet werden, um diese Standardausgabeformate zu ändern oder zu konfigurieren. Die Ausgabewerte yaml, json und csv --format garantieren, dass bei erfolgreichem Abschluss des Befehls Standardausgabedaten ausgegeben werden, die mit dem jeweiligen Format geparst werden können. Eine detaillierte Beschreibung der Funktionen des Flags --format finden Sie mit dem Befehl gdcloud topic formats. Bei Befehlen, die keine Ressourcen zurückgeben, wird die Ausgabe im --help-Flag des Befehls definiert.
Der Standardfehler ist für die Diagnose reserviert. Im Allgemeinen kann sich das Format von Standardfehlerdaten von Release zu Release ändern. Nutzer dürfen keine Skripts für bestimmte Inhalte oder auch nur für das Vorhandensein von Ausgaben im Standardfehlerkanal erstellen. Der einzige zuverlässige Fehlerindikator ist der Exit-Status.
Bei keinem gcloud-CLI-Befehl sollte es zu einem Absturz aufgrund einer nicht abgefangenen Ausnahme kommen. Wenn die gcloud CLI jedoch abstürzt, wird der Stacktrace abgefangen und in die Logdatei geschrieben. Außerdem wird eine Absturzdiagnose in den Standardfehler geschrieben.
Status des Datenexports
Der Exit-Status 0 weist auf einen Erfolg hin. Jeder andere Exit-Status weist auf einen Fehler hin. Befehlsspezifische Diagnosen erläutern die Art des Fehlers und wie er behoben werden kann.