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:
- Utilizzare
services.configs.create
oservices.configs.submit
per inviare le configurazioni del servizio. - Utilizzare
services.configs.list
eservices.configs.get
per recuperare le configurazioni del servizio. - Utilizzo di
services.generateConfigReport
per ottenere un report sulle modifiche tra due configurazioni di servizio.
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:
- OpenAPI v2
- Descrittore dei buffer di protocollo
google.api.Service
in formato JSON o YAML
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",
...
}