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 など、各インサイト タイプに関する情報へのリンクの表については、インサイト タイプ をご覧ください。

権限の設定

ターゲット プロジェクトのインサイトにアクセスするには、権限が必要です。

  • リクエストに請求先プロジェクトが含まれるリクエスト元の場合。リクエストで使用されるプロジェクトは良好な状態でなければなりません。また、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 に変更されています。