Gestione delle configurazioni dei servizi

Questa pagina descrive come gestire le configurazioni dei servizi utilizzando l'Infrastruttura di servizio.

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 Iniziare a utilizzare l'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 farlo 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 l'interfaccia a riga di comando gcloud.

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

Puoi anche chiamare direttamente l'API Service Management per inviare l'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 di configurazione del servizio, è consigliabile chiama services.generateConfigReport per ottenere un report delle modifiche relative a un servizio esistente alla versione precedente della configurazione. Puoi specificare la versione da confrontare utilizzando campo old_config nella richiesta, oppure puoi semplicemente saltare questo campo per genera un report sull'ultima versione della configurazione del servizio.

Supponendo che il nuovo file di configurazione OpenAPI sia chiamato hello.json, puoi esegui 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 specifica versione di configurazione, puoi esegui:

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