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 サービスの名前は Google Cloud上で一意である必要があります。Endpoints ではサービスの識別に DNS と互換性のある名前を使用できるので、サービス名として API のドメイン名やサブドメイン名の使用をおすすめします。これにより、[エンドポイント] の [サービス] ページに表示されるサービス名と API へのリクエストで使用する名前を一致させることができます。Endpoints には、サービス名に関する以下の要件があります。

  • The maximum length of the domain name is 253 characters.
  • The domain name must start with a lowercase letter.
  • Each section in the domain name, which is delimited by dots, has the following requirements:
    • Must start with a lowercase letter.
    • Must not end with a dash.
    • The remaining characters can be lowercase letters, numbers, or dashes.
    • The maximum length is 63 characters.

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

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

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

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

  • App Engine フレキシブル環境でホストされる API の場合は、appspot.com ドメインを使用する必要があり、サービス名は次の形式となります。YOUR_PROJECT_ID は Google Cloud プロジェクト 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 のわかりやすい名前です。コンソールの [エンドポイント] > [サービス] ページには、info.title フィールドで構成したテキストが表示されます。 Google Cloud プロジェクトごとに複数の API がある場合は、最初にページを開くと API 名が一覧表示されます。 Google Cloud API 名をクリックすると、別のページを開いて API の指標やデプロイの履歴やその他の情報を表示できます。

info.version

コンソールの [エンドポイント] > [サービス] ページには、API のバージョン番号が表示されます。 Google Cloud API 構成を初めてデプロイする場合は、事前に以下を行います

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

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

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

operationId

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

次のステップ