Nesta página, descrevemos como gerenciar configurações de serviço usando a infraestrutura de serviços.
Uma configuração de serviço é uma especificação que descreve diferentes aspectos de um serviço gerenciado.
Os métodos da API Service Management normalmente envolvidos no gerenciamento de configurações de serviço são:
- usam
services.configs.create
ouservices.configs.submit
para enviar configurações de serviço. - usam
services.configs.list
eservices.configs.get
para recuperar configurações de serviço. - usam
services.generateConfigReport
para conseguir um relatório de alterações entre duas configurações de serviço.
Antes de começar
Para executar os exemplos deste guia, primeiro siga as instruções para concluir a configuração inicial em Primeiros passos com a API Service Management.
Como enviar arquivos de origem da configuração do serviço
Para atualizar sua configuração de serviço, você precisa enviar uma lista de arquivos de origem de configuração de serviço para a API Service Management. Em seguida, o servidor os compilará em uma configuração de serviço validada.
Os arquivos de origem podem ter os seguintes formatos:
- OpenAPI v2
- Descritor de buffers de protocolo
google.api.Service
no formato JSON ou YAML
A API Service Management não aceita arquivos .proto
. Você precisa
gerar descritores protobuf dos arquivos .proto
antes de enviá-los.
Use o comando a seguir para gerar os arquivos do descritor:
$ protoc hello.proto --include_source_info --include_imports --descriptor_set_out=service.descriptors *.proto
A maneira recomendada de enviar arquivos de origem de configuração de serviços é usar a CLI gcloud.
$ gcloud auth login
$ gcloud endpoints services deploy [a list of service configuration source files]
Também é possível chamar a API Service Management diretamente para enviar arquivos de
origem. Por exemplo, se você tiver esta definição de 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"
}
}
}
}
}
Faça a seguinte chamada de API para enviar a especificação 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.",
...
}
Como gerar relatórios de configuração de serviço
Antes de enviar uma nova versão de configuração de serviço, convém chamar o método services.generateConfigReport
para obter um relatório de alterações relativas a uma versão de configuração de serviço existente. Você pode especificar a versão a ser comparada usando o campo old_config
na solicitação ou simplesmente pular esse campo para gerar um relatório com a versão mais recente da configuração do serviço.
Supondo que o novo arquivo de configuração do OpenAPI seja chamado hello.json
, você pode executar o seguinte comando:
$ 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
Para gerar relatório de uma versão de configuração específica, execute:
# 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
Como receber versões anteriores de configurações de serviço
A API Service Management mantém um histórico de versões das configurações
de serviço enviadas. Você pode listá-las ou recuperar uma versão específica usando os métodos services.configs.list
ou services.configs.get
, conforme mostrado pelos seguintes comandos:
# 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",
...
}