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

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

מיפוי 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).
$apiVersion X-Goog-Api-Version גרסת ה-API שבה רוצים להשתמש. לא כל ממשקי ה-API תומכים בפרמטר הזה: כדאי לעיין במסמכי ה-API לפני שמשתמשים בו.
$.xgafv פורמט שגיאה של JSON. הערכים הנתמכים הם 1 ו-2 (ברירת מחדל). הפורמט של השגיאה 1 צריך לשמש רק את ספריות הלקוח של Google API.
$callback,
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) שבו השרת צריך לסיים את עיבוד הבקשה. פרמטר המערכת הזה חל רק על ממשקי REST API שלא חל עליהם פסק זמן בצד הלקוח.
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-10 פורסמו מסמכי תיעוד של X-Goog-Api-Version.
  • ‫2026-06 עודכנו המסמכים של x-goog-request-params.
  • ‫2021-11 פורסם תיעוד עבור x-goog-request-params.
  • ‫2021-02 פורסם תיעוד עבור quotaUser.
  • יולי 2020: הוצאה משימוש של פרמטרים של שאילתות ב-OAuth 2.0.
  • אוקטובר 2019: הוספת הפרמטר X-Server-Timeout למערכת.
  • ‫2017-10 הוסף פרמטר המערכת X-Goog-User-Project.