サービス構成の管理

このページでは、Service Infrastructure を使用してサービス構成を管理する方法について説明します。

サービス構成とは、マネージドサービスのさまざまな側面を記述した仕様のことです。

サービス構成の管理で一般に使用される Service Management API メソッドは次のとおりです。

サービス構成を送信するには、services.configs.create や services.configs.submit を使用します。
サービス構成を取得するには、services.configs.list と services.configs.get を使用します。
2 つのサービス構成間の変更レポートを取得するには、services.generateConfigReport を使用します。

始める前に

このガイドの例を実行するには、Service Management API スタートガイドの指示に沿って、初期セットアップを完了してください。

サービス構成ソースファイルの送信

サービス構成を更新するには、サービス構成ソースファイルのリストを Service Management API に送信する必要があります。サーバーはこれらを確認済みのサービス構成にコンパイルします。

ソースファイルの形式は次のとおりです。

OpenAPI v2
プロトコルバッファ記述子
JSON または YAML 形式の google.api.Service

Service Management API は .proto ファイルを受け取りません。送信する前に、.proto ファイルから protobuf 記述子を生成する必要があります。記述子ファイルを生成するには、次のコマンドを使用します。

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

サービス構成ソースファイルを送信するには、gcloud CLI の使用をおすすめします。

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

Service Management API を直接呼び出して、ソースファイルを送信することもできます。たとえば、次の 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"
        }
      }
    }
  }
}

次の API 呼び出しを行って 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.",
  ...
}

サービス構成レポートの生成

新しいバージョンのサービス構成を送信する前に、services.generateConfigReport メソッドを呼び出して、現在のサービス構成のバージョンと比較した変更点のレポートを取得できます。比較対象のバージョンをリクエストの old_config フィールドで指定することも、このフィールドを省略して最新の構成バージョンに対するレポートを生成することもできます。

新しい OpenAPI 構成ファイルの名前が hello.json の場合、次のコマンドを実行できます。

$ 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

特定の構成バージョンに対するレポートを生成する場合は、次のコマンドを実行します。

# 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

以前のサービス構成バージョンの取得

Service Management API は、送信済みのサービス構成のバージョン履歴が保管されています。それらの履歴を一覧表示するには services.configs.list メソッドを使用し、特定のバージョンを取得するには services.configs.get メソッドを使用します。コマンドの例については以下をご覧ください。

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