Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

תוספים של 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, כלומר רק ה-methods של ה-API שרשמתם במפרט OpenAPI מוגשים דרך API Gateway.

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

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

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

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

מומלץ להגדיר את ה-API כך שישתמש בניתוב נתיבים תלוי-אותיות. אם משתמשים בניתוב תלוי-אותיות רישיות, ה-API מחזיר קוד סטטוס של HTTP ‏404 כשה-method שנדרש בכתובת ה-URL לא תואם לשם ה-method של ה-API שמופיע במפרט OpenAPI. הערה: במסגרות של אפליקציות אינטרנט כמו Node.js Express יש הגדרה להפעלה או להשבתה של ניתוב תלוי-רישיות. התנהגות ברירת המחדל תלויה במסגרת שבה אתם משתמשים. מומלץ לבדוק את ההגדרות במסגרת כדי לוודא שהניתוב תלוי-אותיות רישיות מופעל. ההמלצה הזו תואמת למפרט 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 backend מחזיר 404. אבל אם אתם משתמשים בניתוב לא תלוי-רישיות, קצה העורפי של ה-API ינתב את הקריאה הזו אל 'widgets'.

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

`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 ללא שרת, צריך להגן על העורף המרוחק כדי לאפשר תעבורה רק מ-API Gateway. כש-API Gateway מעביר בקשות דרך פרוקסי, הוא מצרף טוקן של מזהה מופע לכותרת Authorization. אסימון המזהה של המופע מייצג את חשבון השירות של זמן הריצה ששימש לפריסת API Gateway. לאחר מכן, ה-Backend המרוחק יכול לאמת שהבקשה מגיעה מ-API Gateway על סמך האסימון המצורף.

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

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

כברירת מחדל, API Gateway יוצר את אסימון מזהה המופע עם קהל JWT שתואם לשדה address. צריך לציין את jwt_audience באופן ידני רק אם ה-backend של היעד משתמש באימות מבוסס-JWT והקהל הצפוי שונה מהערך שצוין בשדה jwt_audience.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 כולו. הקצה העורפי חייב לאמת את ה-JWT בכותרת הזו, כי API Gateway לא יבצע אימות כששיטות האימות לא מוגדרות.

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

`disable_auth`

disable_auth: bool

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

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

הקצה העורפי צריך לאפשר הפעלות לא מאומתות.
הקצה העורפי דורש את הכותרת המקורית 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

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

המערכת לא תכבד ערכים לא חיוביים. במקרים כאלה, API Gateway ישתמש באופן אוטומטי בערך ברירת המחדל.

אי אפשר להשבית את מועד סיום ההרשמה, אבל אפשר להגדיר אותו למספר גבוה – לדוגמה, 600 שניות (מועד הסיום המקסימלי).

`protocol`

protocol: [ http/1.1 | h2 ]

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

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

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

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

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

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

דוגמאות:

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). מידע על הגדרת API Gateway לתמיכה ב-CORS מופיע במאמר הוספת תמיכה ב-CORS ל-API Gateway.

אם אתם צריכים להטמיע תמיכה מותאמת אישית ב-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 כדי לספק רשימה של קהלים ששדה ה-JWT‏ aud צריך להתאים להם במהלך אימות JWT. בתוסף הזה אפשר להזין מחרוזת אחת עם ערכים שמופרדים בפסיק. אסור להוסיף רווחים בין הקהלים. אם לא מציינים את השדה הזה, הערך שלו ב-JWT aud צריך להיות זהה לערך בשדה 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`

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

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

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

רכיב	תיאור
name	חובה. השם של המדד הזה. בדרך כלל, זהו סוג הבקשה (לדוגמה, 'בקשות קריאה' או 'בקשות כתיבה') שמזהה באופן ייחודי את המדד.
displayName	אופציונלי, אבל מומלץ. הטקסט שמוצג לזיהוי המדד בכרטיסייה Quotas בדף Endpoints > Services במסוףGoogle Cloud . הטקסט הזה מוצג גם לצרכני ה-API שלכם בדפים Quotas בקטע IAM & admin ובקטע APIs & Services. השם המוצג יכול לכלול עד 40 תווים. לצורך קריאות, היחידה מהמכסה המשויכת מתווספת אוטומטית לשם התצוגה במסוףGoogle Cloud . לדוגמה, אם מציינים 'בקשות קריאה' כשם התצוגה, אז 'בקשות קריאה לדקה לכל פרויקט' מוצג בGoogle Cloud מסוף. אם לא מציינים תווית, המכסה מוצגת לצרכני ה-API בדפי Quotas בקטע IAM & admin ובקטע APIs & Services עם הכיתוב unlabeled quota. כדי לשמור על עקביות עם השמות המוצגים של שירותי 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