本頁面由 Cloud Translation API 翻譯而成。

OpenAPI 2.0 功能限制

OpenAPI | gRPC

以下各節說明 Endpoints 上的 OpenAPI 2.0 功能相關限制。

忽略的範圍

雖然 Endpoints 接受已在安全性配置物件中定義範圍的 OpenAPI 說明文件，但是系統將要求傳送到您的 API 時，可擴充服務 Proxy (ESP)、可擴充服務 Proxy V2 (ESPv2) 或 Cloud Endpoints Frameworks 都不會檢查定義的範圍。

多項安全性要求

您可以在 OpenAPI 文件中指定多項安全要求。本節將說明 ESP 和 ESPv2 支援的安全性配置。

含有 API 金鑰的安全性要求

當安全性配置中有一項是 API 金鑰時，ESP 和 ESPv2 不支援其他的 (邏輯 OR) 安全性要求。舉例來說，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 及其方法使用的所有安全金鑰，都已在 OpenAPI 文件的安全定義中定義。

網址路徑範本

Endpoints 僅支援可對應至整個路徑區段 (以正斜線 / 分隔) 的網址路徑範本參數，不支援只對應部分路徑區段的網址路徑範本參數。

系統支援的網址路徑範本實例如下：

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

系統不支援下列網址路徑範本，因此這類範本會遭到拒絕：

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

網址根路徑 `/` 的作業

Endpoints 接受包含根路徑 / 作業的 OpenAPI 文件，不過根路徑上的要求會遭到可擴充服務 Proxy (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."
}

上傳檔案

端點不接受檔案上傳參數的 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 會忽略大部分的參數與類型定義。

Endpoints 接受包含必要參數及類型定義的 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

外部類型參考資料

Endpoints 不支援 OpenAPI 文件以外類型的參考資料。舉例來說，Endpoints 會拒絕包含下列內容的 OpenAPI 文件：

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

服務主機位址中的自訂通訊埠

Endpoints 不允許在 OpenAPI 文件的 host 欄位中使用自訂通訊埠。舉例來說，Endpoints 會拒絕如下所示的 OpenAPI 文件：

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

YAML 別名限制

Endpoints 在 OpenAPI 文件中最多可支援 200 個 YAML 別名節點。如果 OpenAPI 文件中有超過 200 個 YAML 別名，建議您盡可能取消參照別名，以符合這項限制。

已知錯誤

以下是已知問題。

OpenAPI 文件遭拒

如果您使用 gcloud endpoints services deploy 部署 OpenAPI 文件，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 金鑰定義限制

您的內容必須符合下列其中一個配置，Endpoints 才能在 OpenAPI 文件中指定安全性定義物件內的 API 金鑰：

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"
    },
}

您在部署含有其他類型 API 金鑰安全性定義的 OpenAPI 文件時，Endpoints 可能會接受這些內容，不過同時也會向您發出警告。不過，連入要求中的 API 金鑰安全性定義會遭到系統忽略。

OpenAPI 2.0 功能限制 透過集合功能整理內容 你可以依據偏好儲存及分類內容。