פרמטרים של המערכת

פלטפורמת ה-API של Google מספקת קבוצה של פונקציות משותפות לכל ממשקי ה-API של Google שמבוססים על הפלטפורמה. כדי להשתמש בפונקציונליות כזו ולשלוט בה, הפלטפורמה מגדירה מראש קבוצה מיוחדת של פרמטרים של בקשות שנקראת פרמטרים של המערכת. הפרמטרים האלה זמינים בכל ממשקי ה-API של Google REST ו-gRPC. אפשר לציין פרמטר מערכת באמצעות פרמטר של שאילתת HTTP או כותרת HTTP. בממשקי Google gRPC API, יש תמיכה רק בכותרות HTTP.

רוב המשתמשים לא צריכים להשתמש בפרמטרים האלה ישירות. עם זאת, לעיתים קרובות נעשה בהם שימוש בספריות לקוח שסופקו על ידי Google. אם אתם צריכים לכתוב קוד בהתאמה אישית כדי לגשת ישירות לממשקי Google API, פרמטרים של המערכת יכולים להיות שימושיים במקרים כמו שליטה בהדפסה יפה של JSON או ציון מפתחות API.

מיפוי HTTP

בבקשות HTTP, פרמטרים של המערכת נשלחים כפרמטרים של שאילתות בכתובות URL או ככותרות של בקשות HTTP. לדוגמה, אם יש לכם פרמטר מערכת $foo, הוא נשלח כ-?$foo=xxx בכתובת ה-URL, או כ-?%24foo=xxx אם הוא מקודד בכתובת ה-URL. פרטים נוספים מופיעים בטבלה שלמטה.

מיפוי gRPC

בבקשות gRPC, פרמטרים של המערכת נשלחים ככותרות של בקשות HTTP עם מפתחות באותיות קטנות. פרטים נוספים מופיעים בטבלה הבאה.

הגדרות

בטבלה הבאה מפורטים כל פרמטרי המערכת וההגדרות שלהם.

פרמטר שאילתה של כתובת URL כותרת HTTP/gRPC תיאור
Authorization פרטי כניסה לאימות. פרטים נוספים זמינים במאמר סקירה כללית על אימות.
$alt,
alt		 פורמט תשובה חלופי. הערכים הנתמכים הם json (ברירת מחדל), media, ‏ proto, ‏ sse (JSON streams).
$.xgafv פורמט שגיאה של JSON. הערכים הנתמכים הם 1 ו-2 (ברירת מחדל). הפורמט של השגיאה 1 צריך לשמש רק את ספריות הלקוח של Google API.
$callback,
callback		 פרמטר של קריאה חוזרת ב-JSONP.
$ct Content-Type שינוי של כותרת בקשת HTTP Content-Type.
$fields,
fields		 X-Goog-FieldMask FieldMask משמש לסינון תשובות. אם השדה ריק, צריך להחזיר את כל השדות, אלא אם צוין אחרת במסמכים.
X-HTTP-Method-Override ה-method של ה-HTTP שאליה מכוונת הבקשה. חלק משרתי ה-proxy ברשת לא מקבלים את כל שיטות ה-HTTP.
$key,
key		 X-Goog-Api-Key מפתח Google API. פרטים נוספים זמינים בכתובת https://cloud.google.com/docs/authentication/api-keys.
passwd,
password		 ההגדרה הזו שמורה כדי למנוע הוספה של סיסמאות לכתובות URL.
$prettyPrint,
prettyPrint		 הדפסה יפה של תגובת JSON. הערכים הנתמכים הם true (ברירת מחדל), false.
quotaUser X-Goog-Quota-User מזהה משתמש פסאודונימי לחיוב על בסיס מכסות לכל משתמש. אם לא מציינים את העיקרון, המערכת משתמשת בעיקרון המאומת. אם אין חשבון משתמש מאומת, המערכת תשתמש בכתובת ה-IP של הלקוח. אם מציינים פרויקט מכסה, צריך להשתמש במפתח API תקין עם הגבלות על שירותים כדי לזהות את הפרויקט. אחרת, המערכת מתעלמת מהפרמטר הזה.
$outputDefaults הגדרת פלט של ערכי ברירת מחדל של פרוטו לתגובות JSON.
$unique פרמטר שאילתה ייחודי להשבתת שמירת הבקשה במטמון.
X-Goog-Api-Client זיהוי של לקוח API. הערך הוא רשימה של מחרוזות NAME "/" SEMVER שמופרדות ברווחים, כאשר NAME יכול להכיל רק אותיות קטנות, ספרות ו'-', ו-SEMVER צריך להיות מחרוזת של גרסה סמנטית. לדוגמה: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0.
X-Goog-Request-Reason מכיל סיבה לשליחת הבקשה, שאמורה להירשם ביומן הביקורת. לדוגמה, מספר פנייה לתמיכה. ביומני ביקורת, התווים בסיבה קובעים אם הסיבה מקודדת ב-Base64 לפני שהיא מצורפת לרשומה ביומן. סיבות שמכילות רק אותיות, ספרות ורווחים נשמרות בטקסט פשוט. הסיבות שכוללות תווים אחרים מקודדות ב-base64.
$userProject X-Goog-User-Project פרויקט שצוין על ידי המתקשר למטרות מכסה וחיוב. למבצע הקריאה צריכה להיות הרשאת serviceusage.services.use בפרויקט.
X-Server-Timeout זמן קצוב לתפוגה (בשניות, ערך מסוג float) עד שהשרת יסיים לעבד את הבקשה. פרמטר המערכת הזה חל רק על ממשקי API בארכיטקטורת REST שלא חל עליהם זמן קצוב לתפוגה בצד הלקוח.
x-goog-request-params העברת פרמטרים נוספים לבקשות gRPC. הערך חייב להיות מקודד כמחרוזת שאילתת URL (למשל, key1=value1&key2=value2).

המפתחות והערכים הספציפיים שנתמכים בכותרת הזו תלויים בשירות ובשיטה הספציפיים של Google API שמתבצעת אליהם קריאה. אין קבוצה אחת של פרמטרים שמתאימה לכל הכותרות. כדי לדעת אילו פרמטרים נתמכים או נדרשים, תמיד כדאי לעיין במסמכי התיעוד של ה-API הספציפי שאיתו אתם מבצעים אינטראקציה.

שימושים נפוצים:
  • פרטי ניתוב: בשירותים אזוריים, הכותרת הזו כוללת לעיתים קרובות פרמטרים שעוזרים ל-GFE לנתב את הבקשה אל העורף האזורי הנכון. לרוב מדובר במפתחות שתואמים לחלקים בשם המשאב (למשל, name=projects/my-proj/locations/us-central1, parent=projects/my-proj/locations/us-central1) או בפרמטרים של מיקום מפורש (למשל, grpc-location=locations/us-central1).
  • פונקציונליות ספציפית ל-API: לדוגמה, BigQuery Storage Write API משתמש בפרמטר write_stream בכותרת הזו לקריאות gRPC לאזורים מרובים שאינם בארה"ב (למשל, x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream).
דוגמה:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

יומן שינויים

  • ‫2026-06 עודכנו המסמכים של x-goog-request-params.
  • ‫2021-11 פורסם תיעוד עבור x-goog-request-params.
  • ‫2021-02 פרסום תיעוד עבור quotaUser.
  • ‫2020-07 הוצאו משימוש פרמטרים של שאילתות OAuth 2.0.
  • ‫2019-10 נוסף פרמטר המערכת X-Server-Timeout.
  • ‫2017-10 הוסף פרמטר המערכת X-Goog-User-Project.