OpenAPI 機能の制限

現時点で Cloud Endpoints が対応している OpenAPI 仕様はバージョン 2 のみです。

以下のセクションでは、Endpoints での OpenAPI 機能の制限について説明します。

スコープが無視される

Endpoints は、セキュリティ スキーム オブジェクトでスコープが定義された OpenAPI ドキュメントを受け入れますが、リクエストが API に送信されたとき、Extensible Service Proxy(ESP)と Cloud Endpoints Frameworks のどちらも、定義されたスコープをチェックしません。

複数のセキュリティ要件

OpenAPI ドキュメントに複数のセキュリティ要件を指定できます。このセクションでは、ESP がサポートするセキュリティ スキームについて説明します。

API キーを含むセキュリティ要件

セキュリティ スキームの 1 つが API キーである場合、ESP は択一的(論理 OR)セキュリティ要件をサポートしません。たとえば、ESP では次のセキュリティ要件リストはサポートされません。

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

この定義では、petstore_auth 要件または api_key 要件のどちらかに準拠したリクエストを受け入れるオペレーションが必要です。

ただし、セキュリティ要件の連結(論理 AND)はサポートされているので、API キーと OAuth2 認証の両方を必須にできます。たとえば、次のセキュリティ要件リストはサポートされます。

security:
- petstore_auth: []
  api_key: []

この定義では、petstore_auth 要件と api_key 要件の両方に準拠したリクエストを受け入れるオペレーションが必要です。

OAuth2 のセキュリティ要件

ESP は、OAuth2 認証セキュリティ スキームでのみ択一的(論理 OR)セキュリティ要件をサポートします。たとえば、次のセキュリティ要件リストはサポートされます。

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

URL パス テンプレート

Endpoints は、パスセグメント全体(スラッシュ「/」で区切られた部分)に対応する URL パス テンプレート パラメータのみをサポートします。パスセグメントの一部に対応する URL パス テンプレート パラメータはサポートされません。

たとえば、次の URL パス テンプレートはサポートされます。

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

次の URL パス テンプレートはサポートされず、拒否されます。

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

URL ルートパス「/」上のオペレーション

Endpoints は、ルートパス「/」上のオペレーションを含む OpenAPI ドキュメントを受け入れます。ただし、ルートパス上のリクエストは ESP によって拒否されます。

たとえば、次の 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."
}

パラメータ、スキーマ、型

ESP は、ほとんどのパラメータと型の定義を無視します。

Endpoints は必要なパラメータと型の定義が含まれた OpenAPI ドキュメントを受け取りますが、ESP はこれらの定義を適用することなく、受信リクエストを API に転送します。以下に、ESP で適用されない定義の一部を挙げます。

  • フォームデータ パラメータ:
    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

既知の事象

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 キーの制限

OpenAPI ドキュメントのセキュリティ定義オブジェクトで API キーを指定する場合、Endpoints では次のように指定する必要があります。

  • name フィールドに key を指定する
  • in フィールドに query を指定する

例:

"securityDefinitions": {
  "api_key": {
    "type": "apiKey",
    "name": "key",
    "in": "query"
  }

他の種類の API キーのセキュリティ定義を使用して OpenAPI ドキュメントをデプロイした場合、Endpoints がそれらを受け入れる場合でも警告が出されることがあります。ただし、受信リクエストでは API キーのセキュリティ定義は無視されます。

Cloud Endpoints Portal では構成タイプがレンダリングされない

Endpoints は構成タイプ(定義に allOf が含まれるタイプ)を含む OpenAPI ドキュメントを受け取りますが、Endpoints Portal では構成タイプのドキュメントは生成されません。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

OpenAPI を使用した Cloud Endpoints
ご不明な点がありましたら、Google のサポートページをご覧ください。