Telemetry Reporting

はじめに

このページでは、Service Control API v2 を使用して、Service Infrastructure に統合されたマネージドサービスのテレメトリーレポートを作成する方法について説明します。このチュートリアルは、サービスを Google Cloud に深く統合したいと考えているサービスプロデューサーを対象としています。

Service Infrastructure は、デベロッパーが API とサービスを作成、管理、保護、使用するための基盤となるプラットフォームです。シンプルで一般的なサービス使用モデルを使用し、ユーザーはプロデューサーが管理するサービスを消費します。すべての Google API とGoogle Cloud APIは Service Infrastructure の上に構築されているため、このモデルを使用します。

コンシューマがサービスにアクセスすると、サービスは関連するテレメトリーデータをプラットフォームにレポートします。このため、コンシューマとプロデューサーの両方がアクセスを監視できます。Service Infrastructure では、このプロセスはテレメトリーレポートと呼ばれ、分析、監査、課金、ロギング、モニタリングが含まれます。

Service Control API v2

Service Control API v2 は、Service Infrastructure と統合されたすべてのサービスにテレメトリーレポートを提供するシンプルな services.report メソッドを提供します。このメソッドを使用すると、1 回のメソッド呼び出しで次のことを行うことができます。

分析
監査
課金
ロギング
モニタリング

サービスがテレメトリーデータを Service Control API にレポートすると、データはサービスの構成に応じて、消費者、プロデューサーのいずれか、または両方に配信されます。テレメトリーの設定の詳細については、google.api.Service のロギングとモニタリングのセクションをご覧ください。

サービスから Service Control API を呼び出すには、プロデューサーはプロデューサープロジェクトで Service Control API を有効にして、呼び出し元はサービスに対して適切な権限を持っている必要があります。詳細については、Cloud APIs のスタートガイドと Service Control API のアクセス制御をご覧ください。

リクエストの属性

クライアントがサービスにアクセスするとき、サービスは一連の API リクエストに基づいてアクセスをモデル化し、AttributeContext を使用して各リクエストを記述する必要があります。

Service Control API を使用して API 指標をレポートするには、サービスは次の属性を持つ各リクエストに対して services.report メソッドを呼び出す必要があります。Service Control API は API 指標を生成し、それを Cloud Monitoring に送信します。

属性	説明	例
`origin.ip`	発信者の IP アドレス。	"1.2.3.4"
`api.service`	API サービスの名前	"endpointsapis.appspot.com"
`api.operation`	API メソッドの名前	"google.example.hello.v1.HelloService.GetHello"
`api.version`	API バージョンの文字列	"v1"
`api.protocol`	API プロトコルの名前	"https"
`request.id`	一意のリクエスト ID	"123e4567-e89b-12d3-a456-426655440000"
`request.time`	リクエストのタイムスタンプ	"2019-07-31T05:20:00Z"
`request.method`	HTTP メソッドの名前	"POST"
`request.scheme`	URL スキーム	"https"
`request.host`	HTTP ホストヘッダー	"endpointsapis.appspot.com"
`request.path`	URL パス	"/v1/hello"
`response.code`	レスポンスのステータスコード	200
`response.size`	レスポンスのサイズ（バイト）	100
`response.time`	レスポンスのタイムスタンプ	"2019-07-31T05:20:02Z"
`response.backend_latency`	バックエンドのレイテンシ	"0.007s"

テレメトリーレポートの実行

サービス構成を Service Management API にデプロイし、サービスがクライアントからのリクエストを処理する準備ができたら、デプロイされたサービスの services.report の呼び出しを開始できます。サービスがリクエストを受信した後、services.report を呼び出してテレメトリーレポートを実行する必要があります。

テレメトリーレポートをすばやくテストするには、gcurl コマンドを使用して services.report メソッドを呼び出します。初期設定手順については、Service Control API スタートガイドをご覧ください。

次の例は、gcurl コマンドを使用して HTTP 経由で services.report を呼び出す方法を示しています。

gcurl -d '{
  "service_config_id": "latest",
  "operations": [{
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
      "version": "v1",
      "protocol": "https"
    },
    "request": {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "size": 50,
      "time": "2019-07-31T05:20:00Z",
    },
    "response": {
      "size": 100,
      "code": 200,
      "time": "2019-07-31T05:20:02Z",
      "backend_latency": "0.007s"
    },
    "destination": {
      "region_code": "us-central1"
    }
    "resource": {
      "name": "projects/123/locations/us-central1/workspaces/default"
    }
  }]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report

成功すると、services.report メソッドからのレスポンスは空になります。失敗した場合、API エラーに詳細なエラー情報が含まれます。エラー処理の詳細については、API 設計ガイド > エラーをご覧ください。

本番環境サービスの場合、Google が提供するクライアントライブラリのいずれかを使用して Service Control API を呼び出す必要があります。このようなライブラリは、優れたユーザビリティを提供し、認証などの一般的な機能を自動的に処理します。詳しくはクライアントライブラリの説明をご覧ください。