שם
gdcloud topic command-conventions - Supplementary help for gdcloud command-conventions.
תיאור
העיצוב של פקודות gdcloud CLI מבוסס על קבוצה משותפת של עקרונות ומוסכמות. במסמך הזה מוסבר עליהם בפירוט.
המוסכמות הן יעדים ולא כללים. אם יש חריגים, אפשר לעיין במידע שמופיע בפקודות ספציפיות באמצעות הדגל --help.
היררכיית הפקודות
הפקודות ב-CLI של gdcloud מאורגנות בצורה של עץ, כאשר gdcloud הוא השורש, קבוצות של פקודות הן הצמתים הפנימיים, והפקודות הן הצמתים עם העלים. אפשר להריץ פקודות של קבוצות, אבל רק כדי להציג את טקסט העזרה.
לכל הקבוצות והפקודות יש דגל --help שמציג את טקסט העזרה כפלט רגיל. טקסט העזרה נגזר מהקובץ הניתן להפעלה, ולכן הוא תמיד עדכני, גם כשעוברים בין כמה התקנות של גרסאות שונות.
שורת פקודה
כל פקודה ב-gdcloud בנויה באותו פורמט
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
אפשר לערבב בין ארגומנטים של דגלים וארגומנטים תלויי מיקום, אבל כדי לשמור על עקביות, בדרך כלל מוצגים קודם הארגומנטים תלויי המיקום בסדר מסוים, ואחריהם הארגומנטים של הדגלים בכל סדר.
הערות לגבי השימוש בפקודות
השימוש בפקודה הוא סימון מקוצר שמכיל את השם המלא של הפקודה, את הארגומנטים התלויים במיקום ואת הארגומנטים של הדגלים בסדר ממוין לפי קבוצה. ארגומנטים אופציונליים מופיעים בתוך [ ... ]. לדוגמה
gdcloud foo bar NAME [--format=FORMAT]
זוהי דוגמה לשימוש בפקודה gdcloud foo bar עם ארגומנט תלויי מיקום NAME שהוא חובה, ארגומנט תלויי מיקום EXTRA שהוא אופציונלי וארגומנט דגל --format שהוא אופציונלי.
ארגומנטים תלויי מיקום
הארגומנטים תלויי המיקום מסודרים, וצריך לציין אותם בסדר שבו הם מופיעים ברשימת ההגדרות של הארגומנטים במסמך השימוש בפקודה ובמסמך העזרה.
ארגומנטים של דגלים
שמות הדגלים הם באותיות קטנות עם הקידומת --. בדגלים שמורכבים מכמה מילים משתמשים בתו - (מקף) כמפריד בין המילים.
בהתאם למוסכמות של UNIX, אם מציינים דגל כמה פעמים בשורת הפקודה, רק המופע הימני ביותר נכנס לתוקף. לא מופק אבחון. כך קל להגדיר כינויים לפקודות וסקריפטים של עטיפה שמספקים ערכי ברירת מחדל לדגלים. אפשר לשנות את הערכים האלה בקלות על ידי ציון שלהם בשורת הפקודה של הכינוי או של סקריפט העטיפה.
דגלים בוליאניים
למרות שערך ברירת המחדל של הרבה דגלים בוליאניים הוא false, יש דגלים שערך ברירת המחדל שלהם הוא true. הנוכחות של --flag מגדירה את הדגל לערך true או false, בהתאם לערך שמשתמע משם הדגל.
סימונים חשובים
לדגלים שאינם בוליאניים יש ערך מפורש. כדי לציין את הערך, צריך להוסיף אותו כארגומנט הבא אחרי הדגל --flag value.
אם הערך הוא מספר שלם, הוא צריך להיות 0 ומעלה. אי אפשר להזין מספרים שלמים שליליים.
תשובה
הפלט הרגיל הוא מידע מפורש שהתבקש בפקודה.
בהתאם להקשר, יכול להיות שיהיו הבטחות לגבי פורמט הפלט כדי לתמוך בניתוח דטרמיניסטי. פקודות מסוימות מחזירות משאבים, והמשאבים האלה מופיעים כפלט סטנדרטי בדרך כלל בפורמט טבלה ספציפי לפקודה או בפורמט YAML שמוגדר כברירת מחדל. בנוסף, אפשר להשתמש בדגל --format כדי לשנות או להגדיר את פורמטי הפלט האלה שמוגדרים כברירת מחדל. ערכי הפלט --format של הפקודות yaml, json ו-csv מבטיחים שסיום מוצלח של הפקודה יניב נתוני פלט סטנדרטיים שאפשר לנתח באמצעות הפורמט המתאים. הסבר מפורט על היכולות של הדגל --format זמין בפקודה gdcloud topic formats. בפקודות שלא מחזירות משאבים, הפלט מוגדר בדגל --help של הפקודה.
סטיית התקן שמורה לאבחון. באופן כללי, הפורמט של נתוני שגיאות רגילים עשוי להשתנות מגרסה לגרסה. אסור למשתמשים לכתוב סקריפטים שפועלים על תוכן ספציפי, או אפילו על קיום פלט לשגיאה רגילה. האינדיקטור היחיד שמעיד על שגיאה באופן מהימן הוא סטטוס היציאה.
אף פקודה ב-CLI של gdcloud לא אמורה לקרוס בגלל חריגה שלא נתפסה. עם זאת, אם ה-CLI של gcloud קורס, דוח הקריסות נחסם ונכתב לקובץ היומן, ונתוני אבחון של הקריסה נכתבים לשגיאה הסטנדרטית.
סטטוס היציאה
סטטוס היציאה 0 מציין הצלחה. כל סטטוס יציאה אחר מציין שגיאה. בדיקות האבחון הספציפיות לפקודה יסבירו את מהות השגיאה ואיך לתקן אותה.