設定 Cloud Endpoints

本頁面說明建立由 Endpoints 代管的 gRPC 服務需要的設定檔。

必備條件

本頁假設您已經：

選擇服務名稱

Cloud Endpoints 會使用您在 gRPC API 設定 YAML 檔案中設定的名稱做為服務名稱。

API 服務的名稱在 Google Cloud上不得重複。因為 Endpoints 會使用與 DNS 相容的名稱來識別服務，因此建議您使用 API 的網域名稱或子網域名稱做為服務名稱。使用這個方法時，「Endpoints Services」(Endpoints 服務) 頁面中顯示的服務名稱，會與用來要求您的 API 時所使用的名稱相符。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_path 以讓編譯器能夠搜尋您儲存 .proto 檔案的目錄。

    如果產生描述元檔案的 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 主控台「Endpoints」 >「Services」(服務) 頁面中顯示的標題。例如：

    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 範例