Managing Service Configurations

This page describes how to manage service configurations using Service Infrastructure.

A service configuration is a specification that describes different aspects of a managed service.

The Service Management API methods typically involved in managing service configurations are:

Before you begin

To run the examples in this guide, make sure you first follow the instructions to complete the initial setup in Getting Started with the Service Management API.

Submitting service configurations

The Service Management API provides two ways of submitting new service configurations:

  • Use the Google API Compiler to generate the compiled service configuration and invoke the services.configs.create method to submit it.
  • Embed configuration source files in the API request and invoke the services.configs.submit method to submit the service configuration in its source format. The services.configs.submit method compiles the source file on the server.

Submitting compiled service configurations

If you define your API using protocol buffers, follow the Google API Compiler instructions to generate the compiled service configuration in JSON format.

For example, if you have the following service definition and configuration:

  • The proto service definition (hello.proto):

    syntax = "proto3";
    package google.example.hello.v1;
    option java_multiple_files = true;
    option java_outer_classname = "HelloProto";
    option java_package = "com.google.example.hello.v1";
    
    service HelloService {
      rpc GetHello(GetHelloRequest) returns (GetHelloResponse);
    }
    
    message GetHelloRequest {
      string name = 1;
    }
    
    message GetHelloResponse {
      string response = 1;
    }
    
  • The service configuration (endpointsapis.yaml):

    type: google.api.Service
    config_version: 3
    name: endpointsapis.appspot.com
    title: Hello Endpoints API.
    apis:
    - name: google.example.hello.v1.HelloService
    producer_project_id: endpointsapis
    control:
      environment: servicecontrol.googleapis.com
    http:
      rules:
        - selector: google.example.hello.v1.HelloService.GetHello
          get: /v1/hello
    

Compile and submit the service with Google API Compiler as follows:

# Generate protobuf descriptors.
$ protoc hello.proto --include_source_info --include_imports --descriptor_set_out=service.descriptors

# Compile service configuration. To setup the API compiler, see
# https://github.com/googleapis/api-compiler/
$ ./run.sh \
  --configs endpointsapis.yaml \
  --descriptor service.descriptors \
  --json_out service.json

# Invoke an API call to submit the compiled service configuration.
$ gcurl -X POST -d "@service.json" https://servicemanagement.googleapis.com/v1/services/endpointsapis.appspot.com/configs
{
  "name": "endpointsapis.appspot.com",
  "title": "Hello Endpoints API",
  "id": "2016-07-16r0",
  ...
}

Submitting source service configurations

If you are using the OpenAPI specification to define your API surface, you need to submit the source files directly to the Service Management API and the server will compile them to a service configuration.

For example, if you have this OpenAPI definition (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"
        }
      }
    }
  }
}

You can make the following API call to submit the OpenAPI spec:

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

Generating service configuration reports

Before submitting a new service configuration version, you might want to call the services.generateConfigReport method to get a report of changes relative to an existing service configuration version. You can specify the version to be compared against using the old_config field in the request, or you can simply skip this field to generate a report against the latest service configuration version.

Assuming the new OpenAPI configuration file is called hello.json, you can run the following command:

$ 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

If you want to generate report for a specific configuration version, you can run:

# 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

Getting prior service configuration versions

The Service Management API keeps a history of submitted versions of service configurations. You can list them or retrieve a specific version using the services.configs.list or services.configs.get methods, as illustrated by the following commands:

# 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",
  ...
}
هل كانت هذه الصفحة مفيدة؟ يرجى تقييم أدائنا:

إرسال تعليقات حول...

Service Infrastructure