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

1. כדי להגביל קריאות לא מאומתות, מבטלים את ההרשאה roles/run.invoker לחשבון הראשי המיוחד allUsers.
2. כדי לאפשר רק ל-API Gateway להפעיל את ה-Backend, צריך להקצות את התפקיד 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:

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

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

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

disable_auth

disable_auth: bool

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

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

1. הקצה העורפי צריך לאפשר הפעלות לא מאומתות.
2. הקצה העורפי דורש את הכותרת המקורית 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 או של העברת נתונים בחלקים, מועד היעד עדיין מגביל את משך הזמן של הזרם כולו. בנקודת קצה של gRPC או WebSocket, הוא מגביל את הפער בין ההודעות. במאמר הגדרת תאריך היעד של הזרם מפורטים ערכי הזמן הקצוב לתפוגה שחלים על כל סוג של בקשה. מועד היעד שמוגדר כברירת מחדל הוא 15.0 שניות.

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

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

protocol

protocol: [ http/1.1 | h2 ]

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

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

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

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

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

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

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

• ‫APPEND_PATH_TO_ADDRESS: נתיב הבקשה של ה-backend לטירגוט מחושב על ידי צירוף נתיב הבקשה המקורי לכתובת ה-URL של address של התוסף x-google-backend.
• ‫CONSTANT_ADDRESS: נתיב בקשת היעד הוא קבוע, כפי שמוגדר בכתובת ה-URL של התוסף x-google-backend address. אם הנתיב התואם ב-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). מידע על הגדרת 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.

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 מכיל את השדות הבאים:

לדוגמה:

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

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

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

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

quota

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

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

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

STANDARD: 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 מכיל את הפריט הבא:

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

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

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 משתמש בשם שציינתם בשדה 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