Cloud Endpoints の構成

Google Cloud Endpoints は、OpenAPI 仕様のバージョン 2.0 を使用して記述された API をサポートしています。OpenAPI ドキュメントに、API サーフェスを記述し、Endpoints の機能(認証ルール割り当てなど)を構成します。

Endpoints では、OpenAPI ドキュメントの次の必須フィールドを特別な用途に使用します。

  • host
  • info.title
  • info.version
  • operationId

このページでは、Endpoints によって上記のフィールドがどのように使用されるかについての情報を提供します。この情報を使用すると、OpenAPI ドキュメントをデプロイする準備を完了できます。

前提条件

前提として、このページでは次の点を想定しています。

host

Cloud Endpoints では、OpenAPI ドキュメントの host フィールドで構成した名前がサービス名として使用されます。

API サービスの名前は GCP で一意である必要があります。Endpoints ではサービスの識別に DNS と互換性のある名前を使用できるので、サービス名として API のドメイン名やサブドメイン名の使用をおすすめします。この方法では、[エンドポイント] の [サービス] ページに表示されるサービス名と API へのリクエストで使用される名前が一致します。さらに、サービス名とドメイン名が同じ場合は、API ユーザー用の Cloud Endpoints Portal を作成できます。Endpoints には、サービス名に関する以下の要件があります。

  • ドメイン名の最大長は 253 文字です。
  • ドメイン名の先頭は英小文字にしてください。
  • ドットで区切られたドメイン名の各セクションには、以下の要件があります。
    • 先頭は小文字にしてください。
    • 最後の文字としてダッシュを使用しないでください。
    • 使用できる文字は、小文字、数字、ダッシュです。
    • 最大長は 63 文字です。

独自のカスタム ドメイン(example.com など)を登録することも、Google で管理しているドメインを使用することもできます。

Google が管理するドメインを使用する

Google は、cloud.goog ドメインと appspot.com ドメインを所有し、管理しています。Google が管理するドメインを使用する場合は、サービス名の一部として GCP プロジェクト ID を使用する必要があります。GCP プロジェクトにはグローバルに一意のプロジェクト ID が付いているため、この要件によって一意のサービス名を作成できます。

使用するドメイン名は、API をホストするバックエンドによって異なります。

  • App Engine フレキシブル環境でホストされている API の場合は appspot.com ドメインを使用する必要があり、サービス名は次の形式となります。YOUR_PROJECT_ID は GCP プロジェクト ID です。

    YOUR_PROJECT_ID.appspot.com
    

    App Engine に API をデプロイすると、YOUR_PROJECT_ID.appspot.com 形式の名前の DNS エントリが自動的に作成されます。

  • Compute Engine、Google Kubernetes Engine、または Kubernetes でホストされている API の場合は cloud.goog ドメインを使用する必要があり、サービス名は次の形式となります。YOUR_API_NAME は API の名前です。

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    

    このドメインを API のドメイン名として使用する方法については、cloud.goog ドメインでの DNS の構成をご覧ください。

カスタム ドメインを使用する

Google が管理するドメインを使用しない場合は、使用する権利のあるカスタム ドメイン(myapi.mycompany.com など)を使用できます。API 構成をデプロイする前に、ドメインの所有権の確認の手順を行ってください。

info.title

info.title フィールドは、API のわかりやすい名前です。GCP Console の [Endpoints] > [サービス] ページには、info.title フィールドに設定したテキストが表示されます。1 つの GCP プロジェクトに API が複数ある場合は、最初にページを開いたときに、API 名のリストが表示されます。API 名をクリックすると、別のページを開いて API の指標やデプロイの履歴やその他の情報を表示できます。

info.version

GCP Console の [Endpoints] > [サービス] ページに、API のバージョン番号が表示されます。API 構成を初めてデプロイする場合は、事前に以下を行います。

  • info.version フィールドのバージョン番号を、1.0 などの適切な API バージョンに設定します。

  • basePath フィールドを、/v1 などのメジャー バージョン番号に設定します。

API のバージョニングの詳細については、API ライフサイクル管理をご覧ください。

operationId

operationId は OpenAPI 仕様のオプション フィールドですが、このフィールドはオペレーションの内部識別に使用されるため、Endpoints では必須です。operationId に指定する文字列は、API 内で一意である必要があります。命名に関するガイダンスについては、OpenAPI 仕様の operationId の説明をご覧ください。

次のステップ

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

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

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