使用 API - 数据分析

本页面介绍了如何在 Recommender 中使用 gcloud 命令或 REST API 查看和管理数据分析。

与 Recommender API 交互的典型数据分析是：

列出当前适用于特定数据分析类型的数据分析
将想要执行操作的数据分析标记为已接受

如需了解如何在 Google Cloud Console 中更改数据分析状态，请参阅 Recommendation Hub 的文档，或相应的数据分析类型。

设置默认项目。

设置默认项目（如果尚未设置）：

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 Consumer 角色包含所需的权限。
每种数据分析类型都需要特定权限。请参阅数据分析类型，获取每种数据分析类型（包括必须的权限）相关信息的链接表。

列出数据分析

要列出目标项目中的数据分析，请执行以下操作：

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。