NOME
gdcloud topic command-conventions - Supplementary help for gdcloud command-conventions.
DESCRIZIONE
La progettazione dei comandi dell'interfaccia a riga di comando gcloud segue un insieme comune di principi e convenzioni. Questo documento li descrive in dettaglio.
Le convenzioni sono obiettivi piuttosto che regole. Per eventuali eccezioni, consulta le informazioni fornite per i singoli comandi utilizzando il flag --help.
GERARCHIA DEI COMANDI
I comandi dell'interfaccia a riga di comando gcloud sono organizzati come un albero con gcloud come radice, gruppi di comandi nei nodi interni e comandi nei nodi foglia. I comandi di gruppo sono eseguibili, ma solo per visualizzare il testo della guida.
Tutti i gruppi e i comandi hanno un flag --help che mostra il testo della guida come output standard. Il testo della guida deriva dall'eseguibile in esecuzione, quindi è sempre aggiornato, anche quando si passa da un'installazione di release all'altra.
RIGA DI COMANDO
Ogni comando gcloud segue lo stesso formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
I flag e gli argomenti posizionali possono essere combinati, ma per coerenza, gli argomenti posizionali vengono in genere visualizzati per primi in ordine, seguiti dai flag in qualsiasi ordine.
NOTAZIONE DELL'UTILIZZO DEI COMANDI
L'utilizzo dei comandi è una notazione abbreviata che contiene il nome completo del comando, gli argomenti posizionali e gli argomenti flag in ordine di gruppo. Gli argomenti facoltativi sono racchiusi tra [ ... ]. Ad esempio:
gdcloud foo bar NAME [--format=FORMAT]
Questo è l'utilizzo del comando gdcloud foo bar con un argomento posizionale obbligatorio NAME, un argomento posizionale facoltativo EXTRA e un argomento flag facoltativo --format.
Argomenti posizionali
Gli argomenti posizionali sono ordinati e devono essere specificati nell'ordine elencato nell'elenco delle definizioni degli argomenti della guida e dell'utilizzo dei comandi.
Argomenti di segnalazione
I nomi dei flag sono minuscoli e hanno il prefisso --. I flag composti da più parole utilizzano - (trattino) come separatore di parole.
Seguendo la convenzione UNIX, se un flag viene ripetuto nella riga di comando, ha effetto solo l'occorrenza più a destra. Non viene emessa alcuna diagnostica. In questo modo è facile configurare alias di comando e script wrapper che forniscono valori dei flag predefiniti, valori che possono essere facilmente sostituiti specificandoli nella riga di comando dell'alias o dello script wrapper.
Flag booleani
Mentre molti flag booleani hanno un valore implicito di false, alcuni sono true per impostazione predefinita. La presenza di --flag imposta il flag su true o false, a seconda del valore implicito nel nome del flag.
Flag con valore
I flag non booleani hanno un valore esplicito. Il valore può essere specificato inserendolo come argomento successivo al flag --flag value.
Se il valore è un numero intero, deve essere pari o superiore a 0. I numeri interi negativi non sono accettati.
Output
L'output standard è per le informazioni esplicite richieste dal comando.
A seconda del contesto, potrebbero essere presenti garanzie sul formato di output per supportare l'analisi deterministica. Alcuni comandi restituiscono risorse e queste risorse sono elencate come output standard di solito utilizzando un formato di tabella specifico del comando o il formato YAML predefinito. Inoltre, il flag --format può essere utilizzato per modificare o configurare questi formati di output predefiniti. I valori di output --format di yaml, json e csv garantiscono che il completamento corretto del comando generi dati di output standard che possono essere analizzati utilizzando il formato corrispondente. Una spiegazione dettagliata delle funzionalità del flag --format è disponibile con il comando gdcloud topic formats. Per i comandi che non restituiscono risorse, l'output è definito nel flag --help del comando.
L'errore standard è riservato alla diagnostica. In generale, il formato dei dati di errore standard potrebbe cambiare da una release all'altra. Gli utenti non devono creare script per contenuti specifici o anche per l'esistenza di output nell'errore standard. L'unico indicatore di errore affidabile è lo stato di uscita.
Nessun comando gcloud CLI deve arrestarsi in modo anomalo con un'eccezione non rilevata. Tuttavia, se gcloud CLI si arresta in modo anomalo, la analisi dello stack viene intercettata e scritta nel file di log e viene scritta una diagnostica dell'arresto anomalo nell'errore standard.
Stato uscita
Lo stato di uscita 0 indica che l'operazione è riuscita. Qualsiasi altro stato di uscita indica un errore. La diagnostica specifica per il comando spiegherà la natura dell'errore e come correggerlo.