Gestione delle configurazioni dei servizi

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

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

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

Prima di iniziare

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

Invio dei file di origine della configurazione del servizio in corso...

Per aggiornare la configurazione del servizio, devi inviare un elenco di file di origine della configurazione del servizio all'API Service Management; il server li 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 i descrittori protobuf dai file .proto prima di inviarli. Puoi utilizzare il seguente comando per generare i file descrittori:

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

Il modo consigliato per inviare i file di origine della 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"
        }
      }
    }
  }
}

Puoi effettuare la seguente chiamata API per inviare la specifica 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.",
  ...
}

Generazione di report di configurazione del servizio

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

Supponendo che il nuovo file di configurazione OpenAPI sia denominato hello.json, puoi eseguire questo 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 specifica della configurazione, 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

Recupero delle versioni precedenti della configurazione del servizio

L'API Service Management conserva una cronologia delle versioni delle configurazioni di servizio inviate. Puoi elencarli 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",
  ...
}