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

פלטפורמת ה-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).
$apiVersion X-Goog-Api-Version גרסת ה-API שבה רוצים להשתמש. לא כל ממשקי ה-API תומכים בפרמטר הזה: כדאי לעיין במסמכי ה-API לפני שמשתמשים בו.
$.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 זמן קצוב לתפוגה (בשניות, ערך מספרי עם נקודה עשרונית) עד שהשרת יסיים לעבד את הבקשה. פרמטר המערכת הזה חל רק על ממשקי 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-10 פורסם תיעוד של X-Goog-Api-Version.
  • ‫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.