API の使用 - 分析情報
このページでは、gcloud
コマンドや REST API を使用して、Recommender のインサイトを表示、管理する方法について説明します。
Recommender API でよく行われるインサイトの操作は、次のようなものです。
- 特定のインサイト タイプについて利用可能なインサイトを一覧表示する
- 対応予定の分析情報を承認済みとしてマークする
Google Cloud Console で分析情報の状態を変更する方法については、おすすめハブか、適切な分析情報の種類のドキュメントをご覧ください。
デフォルト プロジェクトの設定
デフォルト プロジェクトをまだ設定していない場合は設定します。
gcloud config set project PROJECT_ID
PROJECT_ID はプロジェクトの ID です。
環境変数の設定
Recommender 操作用の環境変数を設定します。
PROJECT=TARGET_PROJECT_ID LOCATION=LOCATION_ID INSIGHT_TYPE=INSIGHT_TYPE_ID
ここで
TARGET_PROJECT_ID は、インサイトを一覧表示するプロジェクトです。現在のプロジェクトとは異なるプロジェクトを指定できます。
gcloud
コマンドには、このプロジェクト ID を使用する必要があります。- API リクエストには、プロジェクト番号か、プロジェクト ID を使用できます。プロジェクト番号の使用をおすすめします。
プロジェクト番号は、API コマンドと
gcloud
コマンドの両方のレスポンスで返されます。LOCATION_ID は、インサイトに関連付けられたリソースがある Google Cloud ロケーション(
global
またはus-central1-a
)です。INSIGHT_TYPE_ID は、完全修飾されたインサイト タイプ ID(
google.iam.policy.Insight
など)です。
サポートされているロケーションとインサイト タイプ ID など、各インサイト タイプに関する情報へのリンクの表については、インサイト タイプ をご覧ください。
権限の設定
ターゲット プロジェクトのインサイトにアクセスするには、権限が必要です。
- リクエストに請求先プロジェクトが含まれるリクエスト元の場合。リクエストで使用されるプロジェクトは良好な状態でなければなりません。また、
serviceusage.services.use
権限を含むプロジェクト内のロールがユーザーに付与されている必要があります。必要な権限は、Service Usage ユーザーロールに含まれています。 - インサイトの種類ごとに特定の権限が必要です。必要な権限など、各インサイトの種類に関する情報へのリンクの表については、分析情報の種類をご覧ください。
インサイトの一覧表示
ターゲット プロジェクトのインサイトを一覧表示するには、次のようにします。
gcloud
次の情報を入力します。
gcloud recommender insights list \ --project=${PROJECT} \ --location=${LOCATION} \ --insight-type=${INSIGHT_TYPE} \ --format=FORMAT
ここで、FORMAT は、サポートされている gcloud
出力形式(json
など)です。
例:
gcloud recommender insights list \ --project=example-project \ --location=global \ --insight-type=google.iam.policy.Insight \ --format=json
REST
次の情報を入力します。
curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-user-project: ${PROJECT}" \ "https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights"
例:
curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-user-project: example-project" \ "https://recommender.googleapis.com/v1/projects/example-project/locations/us-central1-a/insightTypes/google.iam.policy.Insight/insights"
このオペレーションにより、ターゲット プロジェクトの現在の IAM ポリシー インサイトが、指定された形式の Insight
エンティティのリストとして出力されます。
出力は次のようになります。
[ { "category": "SECURITY", "content": { "condition": { "description": "", "expression": "", "location": "", "title": "" }, "exercisedPermissions": [], "inferredPermissions": [], "member": "user:my-service-account@example-project.iam.gserviceaccount.com", "role": "roles/iam.securityReviewer" }, "description": "0 permission checks were authorized by this policy binding tuple.", "etag": "\"45f4e2c63f6952e8\"", "insightSubtype": "PERMISSIONS_USAGE", "lastRefreshTime": "2020-03-06T08:00:00Z", "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9", "observationPeriod": "7776000s", "stateInfo": { "state": "ACTIVE", }, "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/32428390823" ], } ]
なお、返されるインサイトには、次のフィールドが含まれます。
次の形式の
name
フィールド。projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID
ここで、インサイトは、INSIGHT_ID により一意に識別されます。
現在のインサイトの状態に関連付けられている
etag
フィールド。
後続の gcloud
コマンドまたは REST API 呼び出しを使用してインサイトを参照する場合、インサイト ID と etag の両方を参照します。これにより、インサイトを最後に取得した後に変更していない場合のみ、オペレーションが実行されるようになります。
インサイトを承認済みとしてマークする
インサイトは、承認済みとしてマークすることで、インサイトにより提供された情報に基づいて、関連するリソースに対してアクションを実行する予定があること、または実行済みであることを示すことができます。インサイトが承認されると、ユーザー名がアクターとしてインサイトに割り当てられ、Recommender はコンテンツが新しくなってもインサイトを更新しません。
インサイトを承認済みとしてマークするには、次のようにします。
gcloud
次の情報を入力します。
gcloud recommender insights mark-accepted \ INSIGHT_ID \ --project=${PROJECT} \ --location=${LOCATION} \ --insight-type=${INSIGHT_TYPE} \ --etag=etag \ --state-metadata=STATE_METADATA --format=FORMAT
ここで
- INSIGHT_ID は、インサイトを一覧表示する以前の呼び出しから取得した、インサイトの ID です。
- etag は、返された etag で、インサイトの状態を表します。
- STATE_METADATA は、オペレーションに関するオプションのメタデータです。メタデータは、「KEY=VALUE」のカンマ区切りのリストとして指定します。
例:
gcloud recommender insights mark-accepted \ a523ff7e-ed03-4143-a3a5-5b396b99cba9 \ --project=example-project \ --location=global \ --insight-type=google.iam.policy.Insight \ --etag='"280b34810bba8a1a"' \ --state-metadata=priority=high,tracking_number=12345 --format=json
REST
次の情報を入力します。
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-user-project: ${PROJECT}" \ --data-binary @- \ https://recommender.googleapis.com/v1/projects/${PROJECT}/locations/${LOCATION}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \ << EOM { "etag": "etag", "stateMetadata": STATE_METADATA } EOM
ここで
- INSIGHT_ID は、インサイトを一覧表示する以前の呼び出しから取得した、インサイトの ID です。
- etag は、返された etag で、インサイトの状態を表します。
- STATE_METADATA は、オペレーションに関する追加のメタデータ用のオプション フィールドです。メタデータは、「
key:value
」として指定します。
例:
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "x-goog-user-project: example-project" \ --data-binary @- \ https://recommender.googleapis.com/v1/projects/example-project/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \ << EOM { "etag": "\"280b34810bba8a1a\"" "stateMetadata": { "priority" : "high", "tracking_number": "12345" } } EOM
このオペレーションを実行すると、指定した形式で Insight
エンティティが返されます。
出力は次のようになります。
{ "category": "SECURITY", "content": { ... }, "description": "0 permission checks were authorized by this policy binding tuple.", "etag": "\"356ae51165729f38\"", "insightSubtype": "PERMISSIONS_USAGE", "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com", "lastRefreshTime": "2020-03-06T08:00:00Z", "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9", "observationPeriod": "7776000s", "stateInfo": { "state": "ACCEPTED", "stateMetadata": { "priority" : "high", "tracking_number": "12345" } }, "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/32428390823" ], "userLastUpdateTime": "2020-03-31T20:57:50.509855Z" }
state
フィールドの値が、ACCEPTED
に変更されています。