Gerir configurações de serviços

Esta página descreve como gerir as configurações de serviços através da infraestrutura de serviços.

Uma configuração de serviço é uma especificação que descreve diferentes aspetos de um serviço gerido.

Os métodos da API Service Management normalmente envolvidos na gestão das configurações dos serviços são:

Antes de começar

Para executar os exemplos neste guia, certifique-se de que segue primeiro as instruções para concluir a configuração inicial em Introdução à API Service Management.

Envio de ficheiros de origem da configuração do serviço

Para atualizar a configuração do serviço, tem de enviar uma lista de ficheiros de origem da configuração do serviço para a API Service Management. O servidor compila-os numa configuração do serviço validada.

Os ficheiros de origem podem ter os seguintes formatos:

A API Service Management não aceita ficheiros .proto. Tem de gerar descritores protobuf a partir dos seus ficheiros .proto antes de os enviar. Pode usar o seguinte comando para gerar os ficheiros descritores:

$ protoc hello.proto --include_source_info --include_imports --descriptor_set_out=service.descriptors *.proto

A forma recomendada de enviar ficheiros de origem da configuração do serviço é usar a CLI gcloud.

$ gcloud auth login
$ gcloud endpoints services deploy [a list of service configuration source files]

Também pode chamar a API Service Management diretamente para enviar ficheiros de origem. Por exemplo, se tiver esta definição da 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"
        }
      }
    }
  }
}

Pode fazer a seguinte chamada 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.",
  ...
}

Gerar relatórios de configuração de serviços

Antes de enviar uma nova versão da configuração do serviço, recomendamos que chame o método services.generateConfigReport para receber um relatório das alterações relativas a uma versão da configuração do serviço existente. Pode especificar a versão com a qual quer fazer a comparação através do campo old_config no pedido ou pode simplesmente ignorar este campo para gerar um relatório com a versão de configuração do serviço mais recente.

Supondo que o novo ficheiro de configuração da OpenAPI se chama hello.json, 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

Se quiser gerar um relatório para uma versão de configuração específica, pode executar o seguinte comando:

# 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

Obter versões de configuração de serviços anteriores

A API Service Management mantém um histórico de versões das configurações de serviços enviadas. Pode listá-las ou obter uma versão específica através dos 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",
  ...
}