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 configurações de serviço

A API Service Management oferece duas maneiras de enviar novas configurações de serviço:

  • Use a API Compiler do Google para gerar a configuração de serviço compilada e invoque o método services.configs.create para enviá-la.
  • Incorpore arquivos de configuração de origem na solicitação de API e invoque o método services.configs.submit para enviar a configuração de serviço no formato de origem. O método services.configs.submit compila o arquivo de origem no servidor.

Como enviar configurações de serviço compiladas

Se você definir a API usando buffers de protocolo, siga as instruções da API Compiler do Google para gerar a configuração de serviço compilada no formato JSON.

Por exemplo, se você tiver a seguinte definição e configuração de serviço:

  • a definição do protosserviço (hello.proto):

    syntax = "proto3";
    package google.example.hello.v1;
    option java_multiple_files = true;
    option java_outer_classname = "HelloProto";
    option java_package = "com.google.example.hello.v1";
    
    service HelloService {
      rpc GetHello(GetHelloRequest) returns (GetHelloResponse);
    }
    
    message GetHelloRequest {
      string name = 1;
    }
    
    message GetHelloResponse {
      string response = 1;
    }
    
  • a configuração de serviço (endpointsapis.yaml):

    type: google.api.Service
    config_version: 3
    name: endpointsapis.appspot.com
    title: Hello Endpoints API.
    apis:
    - name: google.example.hello.v1.HelloService
    producer_project_id: endpointsapis
    control:
      environment: servicecontrol.googleapis.com
    http:
      rules:
        - selector: google.example.hello.v1.HelloService.GetHello
          get: /v1/hello
    

Compile e envie o serviço com o Google API Compiler da seguinte maneira:

# Generate protobuf descriptors.
$ protoc hello.proto --include_source_info --include_imports --descriptor_set_out=service.descriptors

# Compile service configuration. To setup the API compiler, see
# https://github.com/googleapis/api-compiler/
$ ./run.sh \
  --configs endpointsapis.yaml \
  --descriptor service.descriptors \
  --json_out service.json

# Invoke an API call to submit the compiled service configuration.
$ gcurl -X POST -d "@service.json" https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs
{
  "name": "endpointsapis.appspot.com",
  "title": "Hello Endpoints API",
  "id": "2016-07-16r0",
  ...
}

Como enviar configurações de serviço de origem

Se você estiver usando a especificação OpenAPI para definir sua superfície de API, precisará enviar os arquivos de origem diretamente para a API Service Management para que o servidor os compile para uma configuração de serviço.

Por exemplo, se você tiver esta definição 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, chame o método services.generateConfigReport para receber um relatório de alterações relativas a uma versão da configuração de serviço atual. Você pode especificar a versão a ser comparada usando o campo old_config na solicitação ou simplesmente ignorar esse campo para gerar um relatório com a versão mais recente da configuração de serviço.

Supondo que o nome do novo arquivo de configuração OpenAPI seja 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 das versões enviadas das configurações de serviço. É possível incluí-las ou recuperar uma versão específica usando os métodos services.configs.list ou services.configs.get, conforme ilustrado 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",
  ...
}
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Service Infrastructure