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

תוספים של OpenAPI 2.0

‫OpenAPI | gRPC

‫Cloud Endpoints מקבל קבוצה של תוספים ספציפיים ל-Google למפרט OpenAPI, שמגדירים את ההתנהגויות של Extensible Service Proxy (ESP),‏ Extensible Service Proxy V2 (ESPv2) ו-Service Control API. בדף הזה מתוארים תוספים ספציפיים ל-Google למפרט OpenAPI 2.0.

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

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

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

`x-google-allow`

x-google-allow: [configured | all]

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

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

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

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

ה-ESP מעבד קריאות ל-API באופן תלוי-רישיות (case-sensitive). לדוגמה, ב-ESP,‏ /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, ‏ ESP חוסם את הבקשה הבאה כי אין לה מפתח API:

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

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

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

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

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

`x-google-backend`

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

כברירת מחדל, ESP מוגדר להעביר את כל התנועה לשרת קצה עורפי מקומי יחיד. כתובת ה-backend המקומי מצוינת על ידי --backend הדגל (ברירת המחדל היא http://127.0.0.1:8081). אפשר להשתמש בתוסף x-google-backend כדי לשנות את התנהגות ברירת המחדל הזו ולציין backend מקומי או מרוחק אחד או יותר שיכולים לקבל בקשות.

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

בהמשך לפי שדה.

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

`address`

address: URL

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

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

אם פעולה משתמשת ב-x-google-backend אבל לא מציינת את address,‏ ESPv2 ינתב בקשות אל ה-backend המקומי שצוין באמצעות הדגל --backend.

`jwt_audience | disable_auth`

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

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

`jwt_audience`

jwt_audience: string

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

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

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

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

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

כשהתכונה הזו מופעלת, ESPv2 משנה את הכותרות בבקשות. אם בקשה מסוימת כבר כוללת את הכותרת Authorization, ‏ ESPv2:

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

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

`disable_auth`

disable_auth: bool

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

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

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

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

`path_translation`

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

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

פרטים נוספים על תרגום נתיבים זמינים בקטע הסבר על תרגום נתיבים.

כשמשתמשים ב-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 שניות.

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

אי אפשר להשבית את מועד סיום ההרשמה, אבל אפשר להגדיר אותו למספר גבוה – לדוגמה, 3600.0 לשעה אחת.

`protocol`

protocol: [ http/1.1 | h2 ]

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

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

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

הפעלת תמיכה בבק-אנד ב-ESP

‫ESPv2 יזהה באופן אוטומטי מתי x-google-backend מוגדר.

כדי להפעיל את התכונה הזו, צריך לשנות את ההגדרה באופן ידני ב-ESP. כדי להפעיל תמיכה ב-x-google-backend ב-ESP, צריך לספק את הארגומנט --enable_backend_routing כשמריצים את מאגר ESP. (בזמן הריצה שבו אין לכם שליטה באפשרויות של מאגר ה-ESP, האפשרות הזו כבר מסופקת לכם). הנה דוגמה להפעלת תמיכה ב-x-google-backend כשפורסים את קונטיינר ה-ESP ב-GKE (הדוגמה הזו מבוססת על הדוגמה מהמדריך בנושא Endpoints ב-GKE):

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

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

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

‫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.

הגדרת DNS בדומיין `cloud.goog`

אם פרסתם את האפליקציה ב-Compute Engine או ב-Google Kubernetes Engine, אתם יכולים ליצור רשומת DNS לשירות Endpoints בדומיין cloud.goog על ידי הוספת הקוד הבא למסמך OpenAPI:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

מוסיפים את התוסף x-google-endpoints ברמה העליונה של מסמך OpenAPI (לא מוזח או מקונן). צריך להגדיר את שם הדומיין בפורמט: .endpoints.PROJECT_ID.cloud.goog

לדוגמה:

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"
  target: "192.0.2.1"

הדומיין .cloud.goog מנוהל על ידי Google ומשותף ביןGoogle Cloud לקוחות. מכיוון שמזהי הפרויקטים הם ייחודיים באופן גלובלי, שם הדומיין בפורמט .endpoints.PROJECT_ID.cloud.goog הוא שם דומיין ייחודי ל-API שלכם. Google Cloud

כדי לפשט את התהליך, מגדירים את השדה host ואת השדה x-google-endpoints.name כך שיהיו זהים. כשפורסים את מסמך ה-OpenAPI, שירות ניהול השירותים יוצר:

שירות מנוהל עם השם שציינתם בשדה host.
רשומת A ב-DNS עם השם וכתובת ה-IP שהגדרתם בתוסף x-google-endpoints.

בממשקי API שמארחים בסביבה הגמישה של App Engine, אפשר להשתמש בדומיין appspot.com. מידע נוסף מופיע במאמר הגדרת נקודות קצה.

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

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

אם אתם צריכים להטמיע תמיכה מותאמת אישית ב-CORS בקוד העורפי, צריך להגדיר את allowCors: True כדי ש-ESP יעביר את כל בקשות ה-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.

‫ESP תומך בשני פורמטים של מפתחות ציבוריים אסימטריים שמוגדרים על ידי התוספים x-google-jwks_uri ו-jwksUri של OpenAPI:

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

OpenAPI 2.0

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

‫OpenAPI 3.x

x-google-auth:
  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

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

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

אם לא מציינים את x-google-jwks_uri או jwksUri, ‏ ESP יפעל לפי פרוטוקול OpenID Connect Discovery כדי לגלות באופן אוטומטי את מזהה ה-URI של JWKS עבור ספק OpenID שצוין. ה-ESP ישלח בקשה אל x-google-issuer/.well-known/openid-configuration, ינתח את תגובת ה-JSON ויקרא את ה-URI של JWKS מהשדה jwks_uri ברמה העליונה.

שימו לב: אם לא תציינו את x-google-jwks_uri או jwksUri, זמני ההפעלה במצב התחלתי (cold start) יהיו ארוכים יותר, כי ה-ESP יצטרך לבצע קריאה נוספת מרחוק בהפעלה. לכן, מומלץ להשמיט את השדה הזה רק אם ה-URI של JWKS משתנה לעיתים קרובות. לרוב ספקי OpenID המוסמכים (כמו Google,‏ Auth0 ו-Okta) יש כתובות URI יציבות של JWKS.

`x-google-jwt-locations`

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

לחלופין, אפשר להשתמש בתוסף 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. בתוסף הזה אפשר להזין מחרוזת אחת עם ערכים שמופרדים בפסיק. אסור להוסיף רווחים בין הקהלים. אם לא מציינים את השדה הזה, השדה aud ב-JWT צריך להיות זהה לשדה host במסמך OpenAPI, אלא אם משתמשים בדגל --disable_jwt_audience_service_name_check. אם משתמשים בדגל ולא מציינים את x-google-audiences, המערכת לא בודקת את השדה aud של JWT.

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 זהה לשם השירות של Endpoints. ‫(Endpoints משתמש בשם שציינתם בשדה 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 endpoints services deploy producer.yaml consumer.yaml

תוספים של OpenAPI 2.0 קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

x-google-allow

דוגמה

x-google-backend

address

jwt_audience | disable_auth

jwt_audience

disable_auth

path_translation

deadline

protocol

הפעלת תמיכה בבק-אנד ב-ESP

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

x-google-endpoints

הגדרת DNS בדומיין cloud.goog

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

x-google-issuer

x-google-jwks_uri

OpenAPI 2.0

‫OpenAPI 3.x

OpenAPI 2.0

‫OpenAPI 3.x

x-google-jwt-locations

x-google-audiences

x-google-management

metrics

quota

x-google-quota

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

x-google-api-name

תוספים של OpenAPI 2.0

`x-google-allow`

`x-google-backend`

`address`

`jwt_audience | disable_auth`

`jwt_audience`

`disable_auth`

`path_translation`

`deadline`

`protocol`

`x-google-endpoints`

הגדרת DNS בדומיין `cloud.goog`

`x-google-issuer`

`x-google-jwks_uri`

`x-google-jwt-locations`

`x-google-audiences`

`x-google-management`

`metrics`

`quota`

`x-google-quota`

`x-google-api-name`