本页面介绍了如何使用 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",
...
}