はじめに
このページでは、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 を呼び出す必要があります。このようなライブラリは、優れたユーザビリティを提供し、認証などの一般的な機能を自動的に処理します。詳しくはクライアント ライブラリの説明をご覧ください。