使用 API - 建议

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

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

  • 列出当前适用于特定 Recommender 的建议
  • 将您打算采纳的建议标记为已占用，或者将您不打算采纳的建议标记为已忽略
  • 使用特定于资源类型（例如 IAM 角色或 Compute Engine 虚拟机实例）的 gcloud 命令或 REST API 调用采纳建议
  • 将建议标记为成功或失败

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

如需了解如何在 Google Cloud 控制台中更改建议的状态，请参阅 Recommendation Hub 或相应的 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

输入以下内容：

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 字段。

当您使用后续的 gcloud 命令或 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

其中：

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

例如：

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

其中：

  • STATE_CHANGE 是您要为建议标记的状态。有效值包括：
    • mark-claimed 可将建议标记为已占用。
    • mark-dismissed 可将建议标记为已忽略。
  • RECOMMENDATION_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/us-central1-a/recommenders/google.compute.instance.MachineTypeRecommender/recommendations/8f20d509-83d2-45d2-8152-1b8d5d7d5831:markClaimed \
<< 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": "\"5e3a63cccf1e0964\"",
  "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": "CLAIMED"
  }
}

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

采纳建议

将建议标记为已占用后，您可以使用特定于资源类型的 gcloud 命令或 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"

更改建议的状态

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

如要将建议标记为成功，请执行以下操作：

gcloud

输入以下内容：

gcloud recommender recommendations STATE_CHANGE \
    RECOMMENDATION_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --recommender=${RECOMMENDER} \
    --etag=etag \
    --state-metadata=priority=high,tracking_number=12345
    --format=FORMAT

Where

  • STATE_CHANGE 是您要对建议进行的更改。有效值包括：
    • mark-succeeded 可将建议标记为成功。
    • mark-failed 可将建议标记为失败。
  • 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 是您要对建议进行的更改。有效值包括：
    • 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。