Como gerenciar configurações de serviço

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:

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:

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