Gestione delle configurazioni dei servizi

Questa pagina descrive come gestire le configurazioni dei servizi utilizzando l'Service Infrastructure.

Una configurazione del servizio è una specifica che descrive diversi aspetti di un servizio gestito.

I metodi dell'API Service Management in genere coinvolti nella gestione delle configurazioni dei servizi sono:

Prima di iniziare

Per eseguire gli esempi in questa guida, assicurati innanzitutto di seguire le istruzioni per completare la configurazione iniziale in Introduzione all'API Service Management.

Invio dei file di origine della configurazione del servizio

Per aggiornare la configurazione del servizio, devi inviare un elenco di file di origine della configurazione del servizio all'API Service Management, che il server compilerà in una configurazione del servizio convalidata.

I file di origine possono avere i seguenti formati:

L'API Service Management non accetta file .proto, devi generare descrittori protobuf dai file .proto prima di inviarli. Puoi utilizzare il seguente comando per generare i file descrittivo:

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

Il modo consigliato per inviare i file di origine di configurazione del servizio è utilizzare gcloud CLI.

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

Puoi anche chiamare direttamente l'API Service Management per inviare i file di origine. Ad esempio, se hai questa definizione 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"
        }
      }
    }
  }
}

Per inviare la specifica OpenAPI, puoi effettuare la seguente chiamata API:

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

Generazione di report sulla configurazione del servizio

Prima di inviare una nuova versione della configurazione del servizio, ti consigliamo di chiamare il metodo services.generateConfigReport per generare un report delle modifiche relative a una versione della configurazione del servizio esistente. Puoi specificare la versione da confrontare utilizzando il campo old_config nella richiesta oppure puoi semplicemente saltare questo campo per generare un report in base all'ultima versione della configurazione del servizio.

Supponendo che il nuovo file di configurazione OpenAPI si chiami hello.json, puoi eseguire il seguente 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 vuoi generare un report per una versione di configurazione specifica, puoi eseguire:

# 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

Ottenere le versioni precedenti della configurazione del servizio

L'API Service Management mantiene una cronologia delle versioni delle configurazioni dei servizi inviate. Puoi elencarle o recuperare una versione specifica utilizzando i metodi services.configs.list o services.configs.get, come illustrato dai seguenti comandi:

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