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 に変更されています。

API の使用 - 分析情報

デフォルト プロジェクトの設定

環境変数の設定

権限の設定

インサイトの一覧表示

gcloud

REST

インサイトを承認済みとしてマークする

gcloud

REST

デフォルトプロジェクトの設定