Cloud Endpoints の構成

このページでは、Endpoints によって管理される gRPC サービスを作成するために必要な構成ファイルについて説明します。

前提条件

このページの説明は、次のことを前提としています。

サービス名を選択する

Cloud Endpoints では、gRPC API 構成の YAML ファイルで構成した名前がサービス名として使用されます。

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

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

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

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

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

YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog`

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

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

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

プロトコル バッファを構成する

  1. サービス用の .proto ファイルを作成します。詳しくは、デベロッパー ガイドをご覧ください。

  2. お使いの言語の protoc コンパイラを使用して、プロトコル バッファをコンパイルします。例:

    protoc
  --proto_path=. \
  --include_imports \
  --include_source_info \
  --descriptor_set_out=api_descriptor.pb \
  bookstore.proto

    上記のコマンドでは、--proto_path が現在の作業ディレクトリに設定されています。gRPC ビルド環境で、.proto 入力ファイルに別のディレクトリを使用する場合は、.proto ファイルを保存したディレクトリをコンパイラが検索するように --proto_path を変更します。

    記述子ファイルを生成する protoc コマンドが失敗する場合は、次の点を確認してください。

    • protoc のバージョンが最新である。
    • インポートされる .proto ファイルのルート ディレクトリとして、--proto_path または短形式 -I を指定している。詳細については、プロトコル バッファのドキュメントをご覧ください。
    • --include_imports を指定している。

    クライアントが HTTP と JSON を使用して gRPC サービスにアクセスする場合は、データを HTTP と JSON から gRPC に変換する方法を指定する必要があります。.proto ファイルに定義されている API に対してアノテーションを指定する方法をおすすめします。詳しくは、HTTP/JSON の gRPC へのコード変換をご覧ください。

gRPC サービス構成ファイルを構成する

gRPC サービス構成 YAML ファイルを作成する必要があります。このファイルには、サービスの名前と使用制限（API キーを必須にするなど）を指定します。Bookstore サンプルの api_config.yaml ファイルをモデルとして使用できます。

  1. api_config.yaml のコピーを保存します。

  2. name フィールドにサービスの名前を入力します。例:

    name: bookstore.endpoints.example-project-12345.cloud.goog

  3. Google Cloud コンソールの [エンドポイント] > [サービス] ページに表示されるタイトルを入力します。例:

    title: Bookstore gRPC API

  4. apis:name フィールドに API 名を入力します。入力するテキストは、.proto ファイルの完全修飾 API 名と正確に一致している必要があります。次に例を示します。

    apis:
  - name: endpoints.examples.bookstore.Bookstore

  5. ファイルの残りの部分を構成します。例:

    #
# API usage restrictions.
#
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true

    詳細については、ルールとセレクタをご覧ください。

次のステップ

追加の gRPC サンプル