‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

תוספי OpenAPI 2.0 ב-API Gateway

‫API Gateway מקבל קבוצה של תוספים ספציפיים ל-Google למפרט OpenAPI, שמגדירים את ההתנהגויות של השער. בדף הזה מתוארות תוספות מותאמות אישית של Google למפרט OpenAPI 2.0, שמשמשות להגדרת ההתנהגויות של API Gateway, כמו ניתוב לקצה העורפי, אימות ותכונות של ניהול ממשקי API.

למרות שהדוגמאות שניתנו הן בפורמט YAML, גם JSON נתמך.

מוסכמה למתן שמות

השמות של תוספי Google OpenAPI מתחילים בקידומת x-google-.

`x-google-allow`

x-google-allow: [configured | all]

התוסף הזה משמש ברמה העליונה של מפרט OpenAPI כדי לציין אילו נתיבי כתובת ה-URL צריכים להיות מורשים דרך API Gateway.

הערכים האפשריים הם configured ו-all.

ערך ברירת המחדל הוא configured, כלומר רק השיטות של ה-API שציינתם במפרט OpenAPI מוגשות דרך API Gateway.

כשמשתמשים ב-all, קריאות לא מוגדרות – עם או בלי מפתח API או אימות משתמש – עוברות דרך API Gateway ל-API שלכם.

‫API Gateway מעבד קריאות ל-API באופן שתלוי באותיות רישיות. לדוגמה, ב-API Gateway,‏ /widgets ו-/Widgets נחשבות לשיטות API שונות.

כשמשתמשים ב-all, צריך לשים לב לשני דברים:

כל מפתח API או כללי אימות.
ניתוב הנתיב לקצה העורפי בשירות שלכם.

מומלץ להגדיר את ה-API כך שישתמש בניתוב נתיבים תלוי אותיות רישיות. כשמשתמשים בניתוב תלוי אותיות רישיות, ה-API מחזיר קוד סטטוס של HTTP של 404 אם ה-method שביקשתם בכתובת ה-URL לא תואמת לשם ה-method של ה-API שמופיע במפרט OpenAPI. שימו לב שבמסגרות של אפליקציות אינטרנט כמו Node.js Express יש הגדרה להפעלה או להשבתה של ניתוב תלוי אותיות רישיות. פעולת ברירת המחדל תלויה במסגרת שבה אתם משתמשים. מומלץ לבדוק את ההגדרות ב-framework כדי לוודא שהניתוב תלוי אותיות רישיות מופעל. ההמלצה הזו תואמת למפרט OpenAPI בגרסה 2.0, שבו נכתב: "כל שמות השדות במפרט תלויי אותיות רישיות".

דוגמה

נניח ש:

‫x-google-allow מוגדר לערך all.
ה-method של ה-API‏ widgets מופיעה במפרט של OpenAPI, אבל לא ב-Widgets.
הגדרתם את מפרט OpenAPI כך שידרוש מפתח API.

בגלל ש-widgets מופיע במפרט של OpenAPI, ‏API Gateway חוסם את הבקשה הבאה כי אין לה מפתח API:

https://my-project-id.appspot.com/widgets

מכיוון שהנתיב Widgets לא מופיע במפרט של OpenAPI, ‏API Gateway מעביר את הבקשה הבאה לשירות שלכם בלי מפתח API:

https://my-project-id.appspot.com/Widgets/

אם ה-API שלכם משתמש בניתוב תלוי אותיות רישיות (ולא ניתבתם קריאות ל-"Widgets" לאף קוד), הקצה העורפי של ה-API יחזיר את השגיאה 404. לעומת זאת, אם אתם משתמשים בניתוב לא תלוי-רישיות, הקצה העורפי של ה-API מנתב את הקריאה הזו אל widgets.

לשפות ולמסגרות שונות יש שיטות שונות לשליטה ברגישות לאותיות רישיות ובניתוב. לפרטים נוספים, עיינו במסמכי התיעוד של ה-framework.

`x-google-backend`

התוסף x-google-backend מציין איך לנתב בקשות לקצוות עורפיים מרוחקים. אפשר לציין את התוסף ברמה העליונה, ברמת הפעולה או בשתי הרמות של מפרט OpenAPI.

התוסף x-google-backend יכול גם לקבוע הגדרות אחרות לקצוות עורפיים מרוחקים, כמו אימות וזמנים קצובים לתפוגה. אפשר להחיל את כל ההגדרות האלה על כל פעולה בנפרד.

התוסף x-google-backend מכיל את השדות הבאים:

`address`

address: URL

חובה. כתובת ה-URL של הקצה העורפי של היעד. הסכימה של הכתובת חייבת להיות http או https.

כשמנתבים לקצוות עורפיים מרוחקים (בלי שרת (serverless)), צריך להגדיר את הכתובת, והסכימה צריכה להיות https.

`jwt_audience | disable_auth`

צריך להגדיר רק אחד משני המאפיינים האלה.

אם בפעולה נעשה שימוש ב-x-google-backend אבל לא צוין jwt_audience או disable_auth, ‏API Gateway יגדיר באופן אוטומטי את ברירת המחדל של jwt_audience כך שתתאים ל-address. אם לא מגדירים את address, ‏API Gateway מגדיר באופן אוטומטי את disable_auth לערך true.

`jwt_audience`

jwt_audience: string

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

כשמגדירים את API Gateway ל-Serverless, צריך לאבטח את הקצה העורפי המרוחק כך שתתאפשר רק תנועה מ-API Gateway. ‫API Gateway יצרף טוקן של מזהה מכונה לכותרת Authorization כשהוא יעביר בקשות דרך שרת proxy. הטוקן של מזהה המכונה מייצג את חשבון השירות בזמן הריצה ששימש לפריסת API Gateway. לאחר מכן, הקצה העורפי המרוחק יכול לאמת שהבקשה הגיעה מ-API Gateway על סמך האסימון המצורף.

לדוגמה, קצה עורפי מרוחק שנפרס ב-Cloud Run יכול להשתמש בניהול זהויות והרשאות גישה (IAM) כדי:

כדי להגביל הפעלות לא מאומתות, צריך לבטל את ההרשאה roles/run.invoker מהחשבון הראשי המיוחד allUsers.
כדי לאפשר רק ל-API Gateway להפעיל את הקצה העורפי, מקצים את התפקיד roles/run.invoker לחשבון השירות של סביבת זמן הריצה של API Gateway.

כברירת מחדל, API Gateway ייצור את טוקן המזהה של המכונה עם קהל JWT שתואם לשדה address. צריך לציין ידנית את jwt_audience רק כשה-backend של היעד משתמש באימות מבוסס-JWT והקהל הצפוי שונה מהערך שצוין בשדה address. במערכות קצה עורפי מרוחקות שנפרסו ב-App Engine או באמצעות שרת proxy לאימות זהויות (IAP), צריך לשנות את קהל ה-JWT. ב-App Engine וב-IAP, מזהה הלקוח ב-OAuth משמש כקהל הצפוי.

כשהתכונה הזו מופעלת, API Gateway משנה את הכותרות בבקשות. אם בבקשה כבר מוגדרת הכותרת Authorization, ‏API Gateway:

מעתיקים את הערך המקורי לכותרת חדשה X-Forwarded-Authorization.
משנים את הכותרת Authorization באמצעות טוקן של מזהה המכונה.

לכן, אם לקוח API מגדיר את הכותרת Authorization, קצה עורפי שפועל מאחורי API Gateway צריך להשתמש בכותרת X-Forwarded-Authorization כדי לאחזר את ה-JWT כולו. ה-backend חייב לאמת את ה-JWT בכותרת הזו, כי API Gateway לא יבצע אימות כששיטות האימות לא מוגדרות.

במאמר יצירת הגדרת API תוכלו למצוא דוגמאות להגדרות.

`disable_auth`

disable_auth: bool

זה שינוי אופציונלי. המאפיין הזה קובע אם API Gateway צריך למנוע קבלת טוקן של מזהה מכונה ולמנוע את הצירוף שלו לבקשה.

כשמגדירים את הקצה העורפי של היעד, יכול להיות שלא תרצו להשתמש ב-IAP או ב-IAM כדי לאמת בקשות מ-API Gateway אם מתקיים אחד מהתנאים הבאים:

ה-backend צריך לאפשר הפעלות לא מאומתות.
ה-backend דורש את הכותרת המקורית Authorization מלקוח ה-API, ולא יכול להשתמש ב-X-Forwarded-Authorization (שמתואר בקטע jwt_audience).

במקרה כזה, צריך להגדיר את השדה הזה ל-true.

`path_translation`

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

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

למידע נוסף על תרגום נתיבים, עיינו בקטע הסבר על תרגום נתיבים.

כשמשתמשים ב-x-google-backend ברמה העליונה של מפרט OpenAPI, ברירת המחדל של path_translation היא APPEND_PATH_TO_ADDRESS. כשמשתמשים ב-x-google-backend ברמת הפעולה של מפרט OpenAPI, ברירת המחדל של path_translation היא CONSTANT_ADDRESS. אם השדה address חסר, השדה path_translation לא יצוין והאירוע לא יתרחש.

`deadline`

deadline: double

זה שינוי אופציונלי. מספר השניות שצריך להמתין לתגובה מלאה לבקשה. תגובות שנמשכות יותר מהמועד האחרון שהוגדר יסתיימו עקב זמן קצוב לתפוגה. בנקודת קצה מסוג SSE או chunked-transfer, המועד האחרון עדיין מגביל את משך הזמן של כל הסטרימינג. בנקודת קצה מסוג gRPC או WebSocket, הוא מגביל את הפער בין ההודעות. בקטע הגדרת המועד האחרון לסטרימינג מפורטים זמני הקצובות לתפוגה שחלים על כל סוג של בקשה. מועד ההגשה שמוגדר כברירת מחדל הוא 15.0 שניות.

כדי להשתמש בברירת המחדל, משמיטים את השדה או מגדירים אותו כ-0 או כערך שלילי.

אפשר להגדיר את המועד האחרון עד 3600 שניות. שער ללא סטרימינג אוכף ערך מקסימלי נמוך יותר של 600 שניות, ודוחה מועד אחרון גבוה יותר ביצירה או בעדכון של השער, ולא ביצירה של הגדרת ה-API.

`protocol`

protocol: [ http/1.1 | h2 ]

זה שינוי אופציונלי. הפרוטוקול שמשמש לשליחת בקשה לקצה העורפי. הערכים הנתמכים הם http/1.1 ו-h2.

ערך ברירת המחדל הוא http/1.1 לקצוות עורפיים של HTTP ו-HTTPS.

ב-HTTP מאובטח לקצה העורפי (https://‎) שתומך ב-HTTP/2, צריך להגדיר את השדה הזה לערך h2 כדי לשפר את הביצועים. זו האפשרות המומלצת לקצוות עורפיים ללא שרת (serverless) ב- Google Cloud .

דרישות הפרוטוקול תלויות בסוג הסטרימינג:

‫gRPC: צריך להגדיר את הפרוטוקול ל-h2.
‫WebSockets: צריך להשתמש ב-http/1.1.
אירועים שנשלחים מהשרת (SSE) ושליחת תשובות מצטברות: אתם יכולים להשתמש ב-http/1.1 או ב-h2. כדי לשפר את הביצועים, מומלץ להשתמש ב-h2.

הסבר על תרגום נתיבים

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

‫APPEND_PATH_TO_ADDRESS: נתיב הבקשה של ה-Target Backend מחושב על ידי הוספת נתיב הבקשה המקורי לכתובת ה-URL של address בתוסף x-google-backend.
‫CONSTANT_ADDRESS: נתיב הבקשה של היעד הוא קבוע, כפי שמוגדר בכתובת ה-URL של address בתוסף x-google-backend. אם הנתיב התואם של OpenAPI מכיל פרמטרים, שם הפרמטר והערך שלו הופכים לפרמטרים של שאילתה.

דוגמאות:

APPEND_PATH_TO_ADDRESS
- address: https://my-project-id.appspot.com/BASE_PATH
- עם פרמטרים של נתיב OpenAPI
  - נתיב OpenAPI: ‏/hello/{name}
  - נתיב הבקשה: /hello/world
  - כתובת ה-URL של בקשת היעד: https://my-project-id.appspot.com/BASE_PATH/hello/world
- בלי פרמטרים של נתיב OpenAPI
  - נתיב OpenAPI: ‏/hello
  - נתיב הבקשה: /hello
  - כתובת ה-URL של בקשת היעד: https://my-project-id.appspot.com/BASE_PATH/hello
CONSTANT_ADDRESS
- address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
- עם פרמטרים של נתיב OpenAPI
  - נתיב OpenAPI: ‏/hello/{name}
  - נתיב הבקשה: /hello/world
  - כתובת ה-URL של בקשת היעד: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
- בלי פרמטרים של נתיב OpenAPI
  - נתיב OpenAPI: ‏/hello
  - נתיב הבקשה: /hello
  - כתובת ה-URL של בקשת היעד: https://us-central1-my-project-id.cloudfunctions.net/helloGET

`x-google-endpoints`

בקטע הזה מתוארים השימושים בתוסף x-google-endpoints.

הגדרת API Gateway כך שיאפשר בקשות CORS

אם ה-API שלכם נקרא מאפליקציית אינטרנט במקור אחר, ה-API צריך לתמוך בשיתוף משאבים בין מקורות (CORS). במאמר הוספת תמיכה ב-CORS ל-API Gateway מוסבר איך להגדיר את API Gateway כך שיתמוך ב-CORS.

אם אתם צריכים להטמיע תמיכה בהתאמה אישית של CORS בקוד של הקצה העורפי, הגדירו את allowCors: True כך ש-API Gateway יעביר את כל בקשות ה-CORS לקוד של הקצה העורפי:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

מוסיפים את התוסף x-google-endpoints ברמה העליונה של מסמך OpenAPI (לא מוזח או מוטמע), לדוגמה:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

`x-google-issuer`

x-google-issuer: URI | EMAIL_ADDRESS

התוסף הזה משמש בקטע securityDefinitions של OpenAPI כדי לציין את מנפיק פרטי הכניסה. הערכים יכולים להיות שם מארח או כתובת אימייל.

`x-google-jwks_uri`

x-google-jwks_uri: URI

כתובת ה-URI של קבוצת המפתחות הציבוריים של הספק, שמשמשת לאימות החתימה של אסימון האינטרנט מסוג JSON.

השדה x-google-jwks_uri (OpenAPI 2.0) או jwksUri (OpenAPI 3.x) הוא שדה חובה. ‫API Gateway תומך בשני פורמטים של מפתחות ציבוריים אסימטריים שמוגדרים על ידי התוסף הזה של OpenAPI:

פורמט של קבוצת JWK. לדוגמה:

OpenAPI 2.0

x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

‫OpenAPI 3.x

jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

X509. לדוגמה:

OpenAPI 2.0

x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

‫OpenAPI 3.x

jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

אם אתם משתמשים בפורמט של מפתח סימטרי, צריך להגדיר את x-google-jwks_uri (OpenAPI 2.0) או את jwksUri (OpenAPI 3.x) ל-URI של קובץ שמכיל את מחרוזת המפתח בקידוד base64url.

הערה: כש-API Gateway שולח בקשות אל x-google-jwks_uri או אל jwksUri, הבקשה תכיל את הכותרת x-forwarded-proto.

`x-google-jwt-locations`

כברירת מחדל, אסימון JWT מועבר בכותרת Authorization (עם הקידומת "Bearer "), בכותרת X-Goog-Iap-Jwt-Assertion או בפרמטר השאילתה access_token.

לחלופין, אפשר להשתמש בתוסף x-google-jwt-locations בקטע securityDefinitions של OpenAPI כדי לספק את המיקומים המותאמים אישית שמהם צריך לחלץ את אסימון ה-JWT.

התוסף x-google-jwt-locations מקבל רשימה של מיקומי JWT. כל מיקום של JWT מכיל את השדות הבאים:

רכיב	תיאור
`header/query`	חובה. השם של הכותרת שמכילה את ה-JWT, או השם של פרמטר השאילתה שמכיל את ה-JWT.
`value_prefix`	זה שינוי אופציונלי. לכותרת בלבד. כשמגדירים את `value_prefix`, הערך שלו צריך להתאים לקידומת של ערך הכותרת שמכיל את ה-JWT.

לדוגמה:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

אם רוצים לתמוך רק בקבוצת משנה של מיקומי ברירת המחדל של JWT, צריך לציין אותם במפורש בתוסף x-google-jwt-locations. לדוגמה, כדי לכלול תמיכה רק בכותרת Authorization עם הקידומת "Bearer ":

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

`x-google-audiences`

x-google-audiences: STRING

התוסף הזה משמש בקטע securityDefinitions של OpenAPI כדי לספק רשימה של קהלים שהשדה aud של JWT צריך להתאים להם במהלך אימות JWT. התוסף הזה מקבל מחרוזת אחת עם ערכים שמופרדים בפסיק. אסור להוסיף רווחים בין הקהלים. אם הוא לא צוין, השדה aud של JWT צריך להתאים לשדה host במסמך OpenAPI.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

`x-google-management`

התוסף x-google-management שולט בהיבטים שונים של ניהול ממשקי API, והוא מכיל את השדות שמתוארים בקטע הזה.

`metrics`

כדי להגדיר מכסה ל-API, משתמשים ב-metrics בשילוב עם quota ו-x-google-quota. מכסה מאפשרת לכם לשלוט בקצב שבו אפליקציות יכולות לקרוא ל-methods ב-API. לדוגמה:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

השדה metrics מכיל רשימה עם צמדי המפתח/ערך הבאים:

רכיב	תיאור
name	חובה. השם של המדד הזה. בדרך כלל זהו סוג הבקשה (לדוגמה, read-requests או write-requests) שמזהה באופן ייחודי את המדד.
displayName	אופציונלי, אבל מומלץ. הטקסט שמוצג כדי לזהות את המדד בכרטיסייה Quotas בדף Endpoints > Services במסוףGoogle Cloud . הטקסט הזה מוצג גם לצרכנים של ה-API בדפים Quotas בקטעים IAM & admin ו-APIs & Services. השם המוצג יכול להכיל עד 40 תווים. כדי לשפר את הקריאוּת, היחידה ממגבלת המכסה המשויכת מצורפת באופן אוטומטי לשם המוצג בGoogle Cloud מסוף. לדוגמה, אם מציינים את השם המוצג Read requests, השם Read requests per minute per project יוצג במסוףGoogle Cloud . אם לא תציינו תווית, למשתמשים ב-API שלכם תוצג "מכסה ללא תווית" בדפים Quotas בקטעים IAM & admin ו-APIs & Services. כדי לשמור על עקביות עם השמות המוצגים של שירותי Google שמופיעים בדף Quotas שמשתמשי ה-API רואים, מומלץ להשתמש בשם המוצג הבא: השתמשו ב "בקשות" כשיש לכם רק מדד אחד. אם יש כמה מדדים, כל אחד מהם צריך לתאר את סוג הבקשה ולהכיל את המילה "בקשות" (לדוגמה, "בקשות קריאה" או "בקשות כתיבה"). אם אחת מהעלויות שמשויכות למדד גדולה מ-1, צריך להשתמש ב "יחידות מכסה" במקום ב "בקשות".
valueType	חובה. חייב להיות INT64
metricKind	חובה. חייב להיות DELTA

`quota`

מגדירים את מגבלת המכסה למדד מסוים בקטע quota. לדוגמה:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

השדה quota.limits מכיל רשימה עם צמדי המפתח/ערך הבאים:

רכיב	תיאור
name	חובה. שם המגבלה, שחייב להיות ייחודי בשירות. השם יכול להכיל אותיות קטנות וגדולות, מספרים ואת התו `-` (מקף), והוא יכול להיות באורך של עד 64 תווים.
מדד	חובה. שם המדד שהמגבלה הזו חלה עליו. השם הזה חייב להיות זהה לטקסט שצוין בשם של מדד. אם הטקסט שצוין לא תואם לשם של מדד, תופיע הודעת שגיאה כשפורסים את מסמך OpenAPI.
יחידה	חובה. יחידת המידה של המגבלה. אפשר להשתמש רק בערך "‎1/min/{project}", כלומר המגבלה נאכפת לכל פרויקט והשימוש מתאפס בכל דקה.
ערכים	חובה. המגבלה של המדד. צריך לציין את זה כצמד מפתח:ערך, בפורמט הבא: STANDARD: `YOUR-LIMIT-FOR-THE-METRIC` מחליפים את `YOUR-LIMIT-FOR-THE-METRIC` במספר שלם שמייצג את המספר המקסימלי של בקשות שמותר לשלוח ביחידה שצוינה (רק לדקה, לכל פרויקט). לדוגמה: values: STANDARD: 5000

`x-google-quota`

התוסף x-google-quota משמש בקטע paths של OpenAPI כדי לשייך שיטה ב-API למדד. בשיטות שלא מוגדר בהן x-google-quota, לא חלות מגבלות מכסה. לדוגמה:

x-google-quota:
  metricCosts:
    read-requests: 1

התוסף x-google-quota מכיל את הפריט הבא:

רכיב תיאור

metricCosts

רכיב	תיאור
metricCosts	צמד מפתח/ערך שמוגדר על ידי המשתמש: `"YOUR-METRIC-NAME": METRIC-COST`. `"YOUR-METRIC-NAME":` הטקסט של `"YOUR-METRIC-NAME"` חייב להתאים לשם של מדד מוגדר. ‫`METRIC-COST:` ערך של מספר שלם שמגדיר את העלות של כל בקשה. כשנשלחת בקשה, המדד המשויך גדל בהתאם לעלות שצוינה. העלות מאפשרת לשיטות לצרוך בקצבים שונים מאותו מדד. לדוגמה, אם למדד יש מגבלת מכסה של 1,000 ועלות של 1, האפליקציה שמבצעת את הקריאה יכולה לשלוח 1,000 בקשות בדקה לפני שהיא חורגת מהמגבלה. אם העלות של אותו מדד היא 2, אפליקציה ששולחת קריאות יכולה לשלוח רק 500 בקשות בדקה לפני שהיא חורגת מהמגבלה.

צמד מפתח/ערך שמוגדר על ידי המשתמש: "YOUR-METRIC-NAME": METRIC-COST.

"YOUR-METRIC-NAME": הטקסט של "YOUR-METRIC-NAME" חייב להתאים לשם של מדד מוגדר.
‫METRIC-COST: ערך של מספר שלם שמגדיר את העלות של כל בקשה. כשנשלחת בקשה, המדד המשויך גדל בהתאם לעלות שצוינה. העלות מאפשרת לשיטות לצרוך בקצבים שונים מאותו מדד. לדוגמה, אם למדד יש מגבלת מכסה של 1,000 ועלות של 1, האפליקציה שמבצעת את הקריאה יכולה לשלוח 1,000 בקשות בדקה לפני שהיא חורגת מהמגבלה. אם העלות של אותו מדד היא 2, אפליקציה ששולחת קריאות יכולה לשלוח רק 500 בקשות בדקה לפני שהיא חורגת מהמגבלה.

דוגמאות למכסות

בדוגמה הבאה מוצגת הוספה של מדד ומגבלה לבקשות קריאה ולבקשות כתיבה.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

`x-google-api-name`

כשהשירות מכיל רק API אחד, שם ה-API זהה לשם השירות של API Gateway. ‫(API Gateway משתמש בשם שציינתם בשדה host של מסמך OpenAPI בתור שם השירות). אם השירות מכיל יותר מ-API אחד, צריך לציין את שמות ה-API על ידי הוספת התוסף x-google-api-name למסמך OpenAPI. התוסף x-google-api-name מאפשר לתת שם מפורש לכל API ולקבוע גרסה נפרדת לכל API.

לדוגמה, אתם יכולים להגדיר שירות בשם api.example.com עם שני ממשקי API,‏ producer ו-consumer, באמצעות קטעי מסמך OpenAPI שמוצגים כאן:

‫Producer API ב-producer.yaml:

swagger: 2.0
host: api.example.com
x-google-api-name: producer
info:
  version: 1.0.3

‫Consumer API ב-consumer.yaml:

swagger: 2.0
host: api.example.com
x-google-api-name: consumer
info:
  version: 1.1.0

אפשר לפרוס את שני מסמכי ה-OpenAPI ביחד באמצעות:

gcloud api-gateway api-configs create API_CONFIG_ID \
  --api=my-api \
  --openapi-spec="producer.yaml,consumer.yaml" \
  --project=my-project-id