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