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 へのリクエストで使用する名前を一致させることができます。また、サービス名とドメイン名が同じ場合は、API ユーザー用の Cloud Endpoints Portal を作成できます。Endpoints には、サービス名に関する以下の要件があります。

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

独自のカスタム ドメイン（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 のわかりやすい名前です。Google Cloud コンソールの [Endpoints] > [サービス] ページには、info.title フィールドで構成したテキストが表示されます。1 つの Google Cloud プロジェクトに複数の API がある場合は、API 名が最初にページを開いたときに一覧表示されます。API 名をクリックすると、別のページを開いて API の指標やデプロイの履歴やその他の情報を表示できます。

info.version

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

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

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

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

operationId

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

次のステップ