מגבלות התכונה OpenAPI 2.0

‫OpenAPI   |  gRPC

בקטעים הבאים מתוארות המגבלות של תכונות OpenAPI 2.0 ב-Endpoints.

היקפי הרשאה שהמערכת התעלמה מהם

למרות ש-Endpoints מקבל מסמכי OpenAPI עם היקפי הרשאות שמוגדרים באובייקט של תוכנית אבטחה, כשבקשה נשלחת ל-API, לא Extensible Service Proxy‏ (ESP), לא Extensible Service Proxy V2‏ (ESPv2) ולא Cloud Endpoints Frameworks בודקים את היקפי ההרשאות המוגדרים.

דרישות אבטחה מרובות

אפשר לציין יותר מדרישת אבטחה אחת במסמך OpenAPI. בקטע הזה מתוארות סכמות האבטחה שנתמכות ב-ESP וב-ESPv2.

דרישות אבטחה שמכילות מפתח API

‫ESP ו-ESPv2 לא תומכים בדרישות אבטחה חלופיות (לוגיות OR) כשמפתח API הוא אחד מסכימות האבטחה. לדוגמה, שירות ESP ו-ESPv2 לא תומכים ברשימת דרישות האבטחה הבאה:

security:
- petstore_auth: []
- api_key: []

ההגדרה הזו מחייבת פעולה לקבלת בקשות שעומדות בדרישות של petstore_auth או api_key.

עם זאת, חשוב לדעת ש-ESP ו-ESPv2 תומכים בצירופים של דרישות אבטחה (AND לוגי), כך שאפשר לדרוש גם מפתח API וגם אימות OAuth2. לדוגמה, רשימת דרישות האבטחה הבאה נתמכת:

security:
- petstore_auth: []
  api_key: []

לפי ההגדרה הזו, פעולה צריכה לקבל בקשות שעומדות בו-זמנית בדרישות של petstore_auth וגם בדרישות של api_key.

דרישות אבטחה ל-OAuth2

‫ESP ו-ESPv2 תומכים בדרישות אבטחה חלופיות (לוגיות OR), אבל רק עבור תוכניות אבטחה לאימות OAuth2. לדוגמה, הרשימה הבאה של דרישות אבטחה נתמכת:

security:
  - firebase1: []
  - firebase2: []

אימות הגדרת האבטחה

‫ESP ו-ESPv2 לא מאמתים שכל דרישות האבטחה (ברמת ה-API או ברמת השיטה) מופיעות גם בקטע securityDefinitions. כתוצאה מכך, אם מפרט ה-API משתמש בסכימת אבטחה לא מוגדרת, בקשות לא מאומתות עשויות לעבור דרך ה-API, ברמה שבה מוגדר מפתח האבטחה הלא מוגדר. מוודאים שכל מפתחות האבטחה שמשמשים את ה-API ואת השיטות שלו מוגדרים בקטע securityDefinitions במסמך OpenAPI.

תבניות של נתיבי כתובות URL

נקודות קצה תומכות רק בפרמטרים של תבנית נתיב כתובת ה-URL שתואמים לפלחי נתיב שלמים (מופרדים באמצעות לוכסנים /). אין תמיכה בפרמטרים של תבנית נתיב כתובת ה-URL שתואמים לפלחי נתיב חלקיים.

לדוגמה, תבניות נתמכות של נתיבי כתובות URL:

• /items/{itemId}
• /items/{itemId}/subitems

תבניות נתיב כתובת ה-URL הבאות לא נתמכות ויידחו:

• /items/overview.{format}
• /items/prefix_{id}_suffix

פעולות בנתיב הבסיסי של כתובת ה-URL‏ /

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

לדוגמה, קטע המסמך הבא של OpenAPI מתקבל:

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

אבל בקשות עוקבות ל-POST / נדחות עם השגיאה הבאה:

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

העלאת קבצים

‫Endpoints לא מקבל את type: file לפרמטרים של העלאת קבצים, צריך להשתמש ב-type: string במקום זאת.

לדוגמה, אסור להשתמש בקטע הקוד הבא type: file:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: file
          description: The file to upload.

אבל מותר לפרסם את המודעות הבאות עם type: string:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes:
        - multipart/form-data
      parameters:
        - in: formData
          name: upfile
          type: string
          description: The file to upload.

פרמטרים, סכימות וסוגים

‫ESP ו-ESPv2 מתעלמים מרוב ההגדרות של פרמטרים וסוגים.

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

• פרמטרים של נתוני טופס, כמו:

  parameters:
  - name: avatar
    in: formData
    description: "The avatar of the user"
    type: string

• פרמטרים נדרשים, כמו:

  parameters:
  - name: message
    in: query
    description: "Message to send"
    required: true
    type: string

• פורמטים של אוספי מערכים, כמו:

  parameters:
  - name: items
    in: query
    description: "List of item IDs"
    required: true
    type: array
    items:
      type: string
    collectionFormat: tsv

• סוג היצירה, למשל:

  definitions:
    base:
      properties:
        message:
          type: string
    extended:
      description: "Extends the base type"
      allOf:
      - $ref: "#/definitions/base"
      - type: object
        properties:
          extension:
            type: string

• אובייקטים שונים של תגובה לכל קוד סטטוס, למשל:

  responses:
    200:
      description: "Echo"
      schema:
        $ref: "#/definitions/EchoResponse"
    400:
      description: "Error"
      schema:
        type: string

הפניות לסוגים חיצוניים

נקודות קצה לא תומכות בהפניות לסוגים מחוץ למסמך OpenAPI. לדוגמה, Endpoints דוחה מסמכי OpenAPI שכוללים:

parameters:
- name: user
  description: User details
  in: body
  schema:
    $ref: "https://example.com/mytype.json"

כתובת מותאמת אישית של מארח השירות לניוד

נקודות קצה לא מאפשרות שימוש ביציאות מותאמות אישית בשדה host של מסמך OpenAPI. לדוגמה, Endpoints דוחה מסמכי OpenAPI כמו:

swagger: 2.0
host: example.com:8080
schemes:
- http

מגבלות על כינויי YAML

נקודות קצה יכולות לתמוך בעד 200 צמתי כינוי של YAML במסמך OpenAPI. אם יש יותר מ-200 כינויי YAML במסמך OpenAPI, מומלץ לבטל את ההפניה לכינויים איפה שאפשר כדי לעמוד במגבלה הזו.

באגים מוכרים

ריכזנו כאן רשימה של בעיות ידועות.

מסמכי OpenAPI נדחו

כשפורסים מסמך OpenAPI באמצעות gcloud endpoints services deploy,‏ Endpoints דוחה מסמכי OpenAPI שכוללים:

• פרמטרים של גוף המערך, כמו:

  parameters:
  - name: message
    description: "Message to echo"
    in: body
    schema:
      type: array
      items:
        type: string

• נתיבים עם לוכסנים בסוף, לדוגמה:

  paths:
    "/echo/":
      post:
        description: "Echo back a given message."
  

  כדי לפתור את הבעיה, מסירים את קו הנטייה בסוף המחרוזת /echo/:

  paths:
    "/echo":
      post:
        description: "Echo back a given message."
  

מגבלות על הגדרות של מפתחות API

כשמציינים מפתח API באובייקט של הגדרות האבטחה במסמך OpenAPI, ‏ Endpoints דורש אחת מהסכימות הבאות:

• הערך בעמודה name הוא key והערך בעמודה in הוא query
• הערך בעמודה name הוא api_key והערך בעמודה in הוא query
• הערך בעמודה name הוא x-api-key והערך בעמודה in הוא header

לדוגמה:

"securityDefinitions": {
  "api_key_0": {
        "type": "apiKey",
        "name": "key",
        "in": "query"
    },
  "api_key_1": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
    }
  "api_key_2": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header"
    },
}

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