管理服務設定

本頁面說明如何利用服務基礎架構管理服務設定。

服務設定是一種規格，用來說明代管服務的各方面資訊。

以下是在管理服務設定時經常用到的 Service Management API 方法：

• 使用 services.configs.create 或 services.configs.submit 提交服務設定。
• 使用 services.configs.list 和 services.configs.get 擷取服務設定。
• 使用 services.generateConfigReport 取得兩個服務設定版本之間的異動報表。

事前準備

如要執行本指南中的範例程式碼，請務必先參閱開始使用 Service Management API 一文，並按照其中說明完成初始設定。

提交服務設定來源檔案

如要更新服務設定，請將服務設定來源檔案清單提交至 Service Management API，伺服器會將這些檔案編譯為經過驗證的服務設定。

來源檔案可為下列格式：

• OpenAPI v2
• 通訊協定緩衝區描述元
• google.api.Service JSON 或 YAML 格式

Service Management API 不會採用 .proto 檔案，您必須先從 .proto 檔案產生 protobuf 描述元，再提交這些描述元。您可以使用下列指令產生描述元檔案：

$ protoc hello.proto --include_source_info --include_imports --descriptor_set_out=service.descriptors *.proto

建議使用 gcloud CLI 提交服務設定來源檔案。

$ gcloud auth login
$ gcloud endpoints services deploy [a list of service configuration source files]

您也可以直接呼叫 Service Management API，提交來源檔案。舉例來說，如果您有以下 OpenAPI 定義 (hello.json)：

{
  "swagger": "2.0",
  "info": {
    "title": "Hello Endpoints API.",
    "description": "Hello Endpoints API.",
    "version": "v1"
  },
  "host": "endpointsapis.appspot.com",
  "schemes": ["https"],
  "paths": {
    "/v1/hello": {
      "get": {
        "tags": ["endpointsapis"],
        "operationId": "GetHello",
        "description": "Returns \"Hello\" with given name in the response.",
        "parameters": [
          {
            "name": "name",
            "description": "Name to be greeted.",
            "in": "query",
            "type": "string"
          }
        ],
        "responses": {
          "default": {
            "description": "Successful operation",
            "schema": {
              "$ref": "#/definitions/GetHelloResponse"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "GetHelloResponse": {
      "description": "Response message for GetHello method.",
      "type": "object",
      "properties": {
        "response": {
          "description": "String of \"Hello \" + `name` provided in the request.",
          "type": "string"
        }
      }
    }
  }
}

您可以利用下列 API 呼叫來提交 OpenAPI 規格：

$ gcurl -d "
{
  'serviceName': 'endpointsapis.appspot.com',
  'configSource':
  {
    'files': [
      {
        'fileContents': '$(base64 hello.json | sed ':a;N;$!ba;s/\n//g')',
        'fileType': 'OPEN_API_JSON',
        'filePath': 'hello.json',
      }
    ]
  }
}" https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs:submit
{
  "name": "operations/serviceConfigs.endpointsapis.appspot.com:a7651c15-9017-4274-b065-d644cc337847",
  "metadata": {
    "@type": "type.googleapis.com/google.api.servicemanagement.v1.OperationMetadata",
    "resourceNames": [
      "services/endpointsapis.appspot.com/configs/2016-07-29r10"
    ],
    "startTime": "2016-07-29r10T23:59:21.081Z",
    "persisted": true
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.servicemanagement.v1.SubmitConfigSourceResponse",
    "serviceConfig": {
      "name": "endpointsapis.appspot.com",
      "title": "Hello Endpoints API.",
  ...
}

產生服務設定報表

提交新的服務設定版本前，建議您先呼叫 services.generateConfigReport 方法，取得與現有服務設定版本比較的異動報表。您可以使用要求中的 old_config 欄位指定要比較的版本，也可以直接略過這個欄位，產生與最新服務設定版本比較的報表。

假設新的 OpenAPI 設定檔名為 hello.json，您可以執行下列指令：

$ gcurl -d "
{
  'newConfig':
  {
    '@type': 'type.googleapis.com/google.api.servicemanagement.v1.ConfigSource',
    'files': [
      {
        'fileContents': '$(base64 hello.json | sed ':a;N;$!ba;s/\n//g')',
        'fileType': 'OPEN_API_JSON',
        'filePath': 'hello.json',
      }
    ],
  }
}" https://servicemanagement.googleapis.com/v1/services:generateConfigReport

如要產生某個設定版本的報表，則可執行：

# Generate config report for the local configration from `/tmp/hello.json`
# and the configration version `2016-07-29r10`.
$ gcurl -d "
{
  'newConfig':
  {
    '@type': 'type.googleapis.com/google.api.servicemanagement.v1.ConfigSource',
    'files': [
      {
        'fileContents': '$(base64 hello.json | sed ':a;N;$!ba;s/\n//g')',
        'fileType': 'OPEN_API_JSON',
        'filePath': 'hello.json',
      }
    ],
  },
  'oldConfig':
  {
    '@type': 'type.googleapis.com/google.api.servicemanagement.v1.ConfigRef',
    'name': 'services/endpointsapis.appspot.com/configs/2016-07-29r10'
  }
}" https://servicemanagement.googleapis.com/v1/services:generateConfigReport

取得先前的服務設定版本

Service Management API 會記錄您提交過的服務設定版本。您可以使用 services.configs.list 或 services.configs.get 方法列出所有版本或擷取特定版本，如下列指令所示：

# List the service configuration history for a managed service.
$ gcurl https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs
{
  "serviceConfigs": [
    {
      "name": "endpointsapis.appspot.com",
      "title": "Hello Endpoints API",
      "id": "2016-07-16r1",
      ...
    },
    {
      "name": "endpointsapis.appspot.com",
      "title": "Hello Endpoints API",
      "id": "2016-07-16r0",
      ...
    }
  ]
}

# Get a specific version of the service configuration for a managed service.
$ gcurl https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs/2016-07-16r0
{
  "name": "endpointsapis.appspot.com",
  "title": "Hello Endpoints API",
  "id": "2016-07-16r0",
  ...
}