管理服务配置

本页面介绍了如何使用 Service Infrastructure 管理服务配置。

服务配置是一种规范，用于描述托管式服务的不同方面。

管理服务配置时，通常需要使用以下 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
Protocol Buffers 描述符
JSON 或 YAML 格式的 google.api.Service

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",
  ...
}