此页面由 Cloud Translation API 翻译。

使用 API - 建议

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

与 Recommender API 交互的典型建议是：

针对特定项目列出建议。
将您打算应用的建议标记为 claimed，或者将您不打算应用的建议标记为 dismissed。
应用这项建议。您可以使用 Google Cloud 控制台中的主动辅助功能自动执行此操作，也可以使用 Google Cloud CLI 命令、REST API 调用或其他工具手动执行此操作。

手动采纳建议时，您使用的命令或调用特定于资源类型。例如，若要更改虚拟机实例的大小来响应虚拟机实例容量 Recommender 的建议，您可以使用 Compute Engine gcloud 命令或调用 Compute Engine REST API。

执行这些操作时，请使用返回的 Recommendation 实体的 OperationsGroup 数组中 resource 字段的值标识目标资源。此字段采用以下格式：
```
//API_NAME/RESOURCE_PATH
```
例如：
```
//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1
```
将建议标记为 succeeded 或 failed。

请注意，只有通过 API 检索的建议才能通过 API 或 BigQuery Export 进行交互。

如需了解如何在Google Cloud 控制台中更改建议的状态，请参阅 Active Assist 或相应的 Recommender 的文档。

设置默认项目

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

gcloud config set project PROJECT_ID

其中 PROJECT_ID 是项目 ID。

设置环境变量

为 Recommender 互动设置环境变量：

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

其中：

TARGET_PROJECT_ID 是要列出其建议的项目。该项目可以是当前项目以外的项目。
- 对于 gcloud 命令，您必须使用项目 ID
- 对于 API 请求，您可以使用项目编号或项目 ID。建议使用项目编号。
项目编号在 API 和 gcloud 命令返回的响应中返回。
LOCATION_ID 是与建议关联的资源所在的 Google Cloud 位置（例如 global 或 us-central1-a）。
RECOMMENDER_ID 是完全限定的 Recommender ID（例如 google.compute.instance.MachineTypeRecommender）。

请参阅 Recommender，获取每个 Recommender（包括支持的位置和 Recommender ID）相关信息的链接表。

设置权限

您必须拥有访问目标项目中建议的权限。

对于在请求中包含结算项目的请求者。请求中使用的项目必须信誉良好，并且用户在项目中必须具有角色，此角色包含 serviceusage.services.use 权限。Service Usage Consumer 角色包含所需的权限。
每个 Recommender 都需要特定权限。请参阅 Recommender，获取每个 Recommender（包括所需权限）相关信息的链接表。

列出建议

如 gcloud Beta 版标签页所示，您可以列出项目的所有建议，而无需指定位置和 Recommender。此功能处于预览版阶段。

正式版功能要求您指定项目、位置和 Recommender。如需了解详情，请参阅 gcloud 标签页。

gcloud Beta 版

输入以下内容：

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

其中，FORMAT 是受支持的 gcloud 输出格式，例如 json。

例如：

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

gcloud

输入以下内容：

gcloud recommender recommendations list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --format=FORMAT

其中，FORMAT 是受支持的 gcloud 输出格式（例如 json）。

例如：

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --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}/recommenders/${RECOMMENDER}/recommendations"

例如：

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/recommenders/google.compute.instance.MachineTypeRecommender/recommendations"

此操作会将目标项目中的当前虚拟机实例容量建议输出为采用指定格式的 Recommendation 实体列表。

输出类似于以下内容：

[
  {
    "content": {
      "operationGroups": [
        {
          "operations": [
            {
              "action": "test",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "valueMatcher": {
                "matchesPattern": ".*zones/us-central1-a/machineTypes/n1-standard-4"
              }
            },
            {
              "action": "replace",
              "path": "/machineType",
              "resource": "//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1",
              "resourceType": "compute.googleapis.com/Instance",
              "value": "zones/us-central1-a/machineTypes/custom-2-5120"
            }
          ]
        }
      ]
    },
    "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
    "etag": "\"280b34810bba8a1a\"",
    "lastRefreshTime": "2019-06-28T06:49:21Z",
    "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
    "primaryImpact": { ... },
    "stateInfo": {
      "state": "ACTIVE"
    },
    "recommenderSubtype": "CHANGE_MACHINE_TYPE"
  }
]

请注意，返回的建议包括以下字段：

采用以下格式的 name 字段：

projects/PROJECT_ID/locations/LOCATION/recommenders/RECOMMENDER_ID/recommendations/RECOMMENDATION_ID

其中，RECOMMENDATION_ID 唯一标识建议

与当前建议状态关联的 etag 字段。

当您使用后续的 Google Cloud CLI 命令或 REST API 调用引用建议时，请同时引用建议 ID 和 Etag，以确保只有在上次检索建议后没有任何更改的情况下执行所有操作。

更改建议的状态

您可以将建议标记为已占用，以表示您打算将建议的更改应用于关联的资源。当建议被占用后，您的用户名将被指定为建议的执行者，且 Recommender 将不再使用新内容更新建议。

您可以将建议标记为已忽略，以表示您不打算将建议的更改应用于关联的资源，或者您不想继续看到该建议。忽略一条建议后，它将不再显示为“有效”建议。Recommender 可能会继续使用较新内容来更新建议。

在采纳建议后，您可以将其标记为成功或失败。

如需更改建议的状态，请完成以下步骤：

gcloud

输入以下内容：

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=ETAG \
    --state-metadata=STATE_METADATA \
    --format=FORMAT

Where

STATE_CHANGE 是您要对建议进行的更改。有效值包括：
- mark-claimed 可将建议标记为已占用。
- mark-dismissed 可将建议标记为已忽略。
- mark-succeeded 可将建议标记为成功。
- mark-failed 可将建议标记为失败。
RECOMMENDATION_ID 是从上一次列出建议调用中检索到的建议 ID。
ETAG 是返回的表示建议状态的 ETag
STATE_METADATA 是该操作的可选元数据。将元数据指定为以英文逗号分隔的 KEY=VALUE 对列表。如果将建议标记为已占用、成功或失败，则此选项可用。

例如：

gcloud recommender recommendations mark-succeeded \
    a523ff7e-ed03-4143-a3a5-5b396b99cba9 \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --etag='"5e3a63cccf1e0964"' \
    --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}/recommenders/${RECOMMENDER}/recommendations/RECOMMENDATION_ID:STATE_CHANGE \
<< EOM
{
  "etag": "ETAG"
  "stateMetadata": STATE_METADATA
}
EOM

其中：

RECOMMENDATION_ID 是从上一次列出建议调用中检索到的建议 ID。
STATE_CHANGE 是您要对建议进行的更改。有效值包括：
- markClaimed 可将建议标记为已占用。
- markDismissed 可将建议标记为已忽略。
- markSucceeded 可将建议标记为成功。
- markFailed 可将建议标记为失败。
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/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markSucceeded \
<< EOM
{
  "etag": "\"280b34810bba8a1a\""
  "stateMetadata": {
    "priority" : "high",
    "tracking_number": "12345"
  }
}
EOM

此操作完成后，会以指定的格式返回 Recommendation 实体。

输出类似于以下内容：

{
  "content": {
    "operationGroups": [ ... ]
  },
  "description": "Save cost by changing machine type from n1-standard-4 to custom-2-5120.",
  "etag": "\"5e3a63cccf1e053c\"",
  "lastRefreshTime": "2019-06-28T06:49:21Z",
  "name": "projects/32428390823/locations/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/a523ff7e-ed03-4143-a3a5-5b396b99cba9",
  "primaryImpact": { ... },
  "stateInfo": {
    "state": "SUCCEEDED",
    "stateMetadata": {
      "priority" : "high",
      "tracking_number": "12345"
    }
  }
}

请注意，state 字段的值已更改为 SUCCEEDED。