はじめに
このページでは、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.check メソッドを提供します。このメソッドを使用すると、1 回のメソッド呼び出しで次のことを行うことができます。
- ステータス チェック
- 不正使用ステータス
- 課金ステータス
- コンシューマーのステータス
- サービスのステータス
- サービスの有効化
- 認証
- GoogleOAuth アクセス トークン
- Google サービスアカウントの署名された JWT
- 承認
- 監査
- Cloud Audit Logging監査ログは、サービス「externalaudit.googleapis.com」に関連付けられます。
サービスが Service Control API を呼び出すとき、プロデューサーは Service Control API のコンシューマーでもあります。したがって、services.check メソッドは、Service Control API の呼び出しでアドミッション コントロールも実行します。
サービスが Service Control API を呼び出すには、プロデューサー プロジェクトで Service Control API を有効にし、サービスに対する適切な権限を持っている必要があります。詳細については、Cloud API のスタート ガイドと Service Control の Access Control をご覧ください。
リクエストの属性
クライアントがサービスにアクセスするとき、サービスはアドミッション コントロールでチェックできる 1 つ以上の API リクエストへのアクセスを抽象化する必要があります。ほとんどの場合、そのようなアクセスは実際に本物の API リクエストです。それ以外の場合には、アクセスは複雑なデータ インポート ジョブまたは SQL クエリであり、サービスは一連の仮想 API リクエストの観点からアクセスをモデル化し、各リクエストでアドミッションコントロールを実行する必要があります。
Service Control API を使用してアドミッション コントロールを実行するには、サービスが必要なリクエストの属性を指定して services.check メソッドを呼び出す必要があります。次の表に、アドミッション コントロールに必要な属性を示します。詳細な仕様については、AttributeContextをご覧ください。
| 属性 | 説明 | 例 |
|---|---|---|
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" |
request.headers |
HTTP リクエストヘッダー必要なヘッダーは、"authorization"、"user-agent", "origin"、"referer"です。 | |
resource.name |
ターゲット リソース名。 | "projects/123/topics/news-feed" |
リソースの属性
クライアントがサービスにアクセスするとき、アクセスには、サービス内の 1 つ以上のリソース（オブジェクトの読み取りや VM インスタンスの作成など）が含まれる場合があります。サービスは、Service Infrastructure アドミッション制御を使用して、IAMとCloud 監査ログでサポートされるリソースのアクセス制御を行うことができます。サービスがアクセス コントロールを必要としない場合は、このセクションをスキップできます。
アクセス コントロールでは、サービスはリクエストの属性とともにリソースの属性を services.check メソッドに渡す必要があります。次の表は、アクセス制御に必要なリソースの属性を示しています。
| 属性 | 説明 | 例 |
|---|---|---|
name |
リソース名。 | "projects/123/locations/global/instances/instance-1" |
type |
リソースの型。 形式は ”{service}/{Kind}” です。 | "endpointsapis.appspot.com/Instance" |
permission |
リソースのアクセス許可。形式は ”{service}/{kinds}.{verb}” です。 | "endpointsapis.appspot.com/instances.get" |
パフォーマンスと効率性に関して、services.check メソッドを使用すると、1 回の呼び出しで 1 つのリソースに対する複数の権限を確認できます。
アドミッション コントロールの実行
サービス構成を Service Management API にデプロイし、サービスがクライアントからのリクエストを処理する準備ができたら、デプロイされたサービスの services.check の呼び出しを開始できます。サービスがリクエストを受信するたびに、services.check を呼び出してアドミッション コントロールを実行する必要があります。
gcurl コマンドを使用して services.check メソッドを呼び出すと、アドミッション コントロールをすばやく試せます。初期設定手順については、Service Control API スタートガイドをご覧ください。
次の例は、gcurl コマンドを使用して HTTP 経由で services.check を呼び出す方法を示しています。
gcurl -d '{
"service_config_id": "latest",
"attributes": {
"origin": {
"ip": "1.2.3.4"
},
"api": {
"service": "endpointsapis.appspot.com",
"operation": "google.example.hello.v1.HelloService.GetHello",
"version": "v1",
"protocol": "https"
}
},
"request": {
"id": "123e4567-e89b-12d3-a456-426655440000",
"time": "2019-07-31T05:20:00Z",
"scheme": "https",
"host": "endpointsapis.appspot.com"
"headers": {
"authorization": "Bearer xxx",
"user-agent": "curl/1.0"
}
},
"resources": [
]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}
services.check メソッドからのレスポンスは、アドミッション コントロールが成功したかどうかを示します。成功した場合、応答は空になります。失敗した場合、レスポンスの status には、サービスがクライアントに返す必要があるエラー情報が含まれます。多くの場合、サービスはエラー情報を独自の形式に変換する必要があります。このサービスでは、ロギングやモニタリングの目的でこの情報を使用することもできます。
本番環境サービスの場合、Google が提供するクライアントライブラリのいずれかを使用して Service Control API を呼び出す必要があります。このようなライブラリは、優れたユーザビリティを提供し、認証などの一般的な機能を自動的に処理します。詳しくはクライアント ライブラリの説明をご覧ください。