本頁面由 Cloud Translation API 翻譯而成。

使用 API - 洞察

本頁說明如何使用 gcloud 指令或 REST API，在 Recommender 中查看及管理深入分析。

與 Recommender API 互動以取得洞察資訊的典型流程如下：

列出特定專案的洞察資料
將您打算採取的洞察資訊標示為「已接受」

如要瞭解如何變更 Google Cloud 控制台中的洞察狀態，請參閱建議中心或適當洞察類型的說明文件。

設定預設專案

如果尚未設定預設專案，請按照下列步驟操作：

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 權限。「服務使用情形消費者」角色包含必要權限。
每種洞察類型都需要特定權限。如需各洞察類型 (包括必要權限) 的相關資訊，請參閱「洞察類型」一文中的連結表格。

列出洞察資料

如 gcloud Beta 分頁所示，您可以列出專案的所有洞察，不必指定位置和建議事項。這項功能目前為預先發布版。

如要使用正式發布的 GA 功能，您必須指定專案、位置和建議事項。詳情請參閱「gcloud」分頁。

gcloud Beta 版

輸入下列指令：

gcloud beta recommender insights list \
    --project=${PROJECT} \
    --format=FORMAT

其中 FORMAT 是支援的Google Cloud CLI 輸出格式，例如 json。

例如：

gcloud beta recommender insights list \
    --project=example-project \
    --format=json

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 是洞察的專屬 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。