Gérer des configurations de service

Cette page explique comment gérer les configurations de service à l'aide de Service Infrastructure.

Une configuration de service est une spécification décrivant différents aspects d'un service géré.

Pour gérer les configurations de service, l'API Service Management fait généralement appel aux méthodes suivantes :

Avant de commencer

Pour exécuter les exemples de ce guide, assurez-vous d'abord d'appliquer la configuration initiale en suivant les instructions de la page Premiers pas avec l'API Service Management.

Envoyer des fichiers source de configuration de service

Pour mettre à jour votre configuration de service, vous devez envoyer une liste de fichiers source de configuration de service à l'API Service Management. Le serveur les compile alors pour produire une configuration de service validée.

Les fichiers source peuvent suivre l'un des formats ci-dessous :

L'API Service Management n'accepte pas les fichiers .proto. Vous devez générer des descripteurs protobuf à partir de vos fichiers .proto avant de les envoyer. Vous pouvez utiliser la commande suivante pour générer les fichiers descripteurs :

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

La méthode recommandée pour envoyer les fichiers sources de la configuration de service consiste à utiliser la gcloud CLI.

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

Vous pouvez également appeler directement l'API Service Management pour envoyer des fichiers source. Par exemple, si vous avez cette définition 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"
        }
      }
    }
  }
}

Vous pouvez envoyer la spécification OpenAPI en effectuant l'appel d'API suivant :

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

Générer des rapports de configuration de service

Avant d'envoyer une nouvelle version de configuration de service, vous pouvez obtenir un rapport des modifications apportées à une version existante en appelant la méthode services.generateConfigReport. Vous pouvez spécifier la version à comparer à l'aide du champ old_config dans la requête, ou vous pouvez simplement ignorer ce champ pour générer un rapport selon la dernière version de configuration du service.

En supposant que le nouveau fichier de configuration OpenAPI s'appelle hello.json, vous pouvez exécuter la commande suivante :

$ 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

Si vous souhaitez générer un rapport pour une version de configuration spécifique, vous pouvez exécuter la commande suivante :

# 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

Obtenir des versions de configuration de service antérieures

L'API Service Management conserve un historique des versions des configurations de service envoyées. Vous pouvez les répertorier ou récupérer une version spécifique à l'aide des méthodes services.configs.list ou services.configs.get, comme illustré dans les commandes suivantes :

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