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 は、完全修飾されたインサイト タイプ IDgoogle.iam.policy.Insight など)です。

サポートされているロケーションとインサイト タイプ ID など、各インサイト タイプに関する情報へのリンクの表については、インサイト タイプ をご覧ください。

権限の設定

ターゲット プロジェクトのインサイトにアクセスするには、権限が必要です。これらの権限は、インサイトのタイプによって異なります。必要な権限など、各インサイト タイプに関する情報へのリンクの表については、インサイトのタイプをご覧ください。

インサイトの一覧表示

ターゲット プロジェクトのインサイトを一覧表示するには、次のようにします。

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