使用 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
。