使用 API - 建議內容

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

與 Recommender API 互動時，通常會進行下列操作：

  1. 列出特定專案的建議。

  2. 將要套用的最佳化建議標示為 claimed，或將不打算套用的最佳化建議標示為 dismissed。

  3. 套用最佳化建議。您可以在 Google Cloud 控制台中使用 Active Assist 自動執行這項操作，也可以使用 Google Cloud CLI 指令、REST API 呼叫或其他工具手動執行。

    手動套用最佳化建議時，您使用的指令或呼叫會因資源類型而異。舉例來說，如要根據 VM 執行個體大小建議工具的建議變更 VM 執行個體大小，您可以使用 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

  4. 將建議標示為 succeeded 或 failed。

請注意，只有透過 API 擷取的建議，才能透過 API 或 BigQuery Export 進行互動。

如要瞭解如何在Google Cloud 控制台中變更建議的狀態，請參閱 Active Assist 或適當建議工具的說明文件。

設定預設專案

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

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 是完整的推薦工具 ID (例如 google.compute.instance.MachineTypeRecommender)。

如要查看每個建議工具的相關資訊 (包括支援的位置和建議工具 ID) 連結表格，請參閱「建議工具」。

設定權限

您必須具備權限，才能存取目標專案中的建議。

  • 要求者在要求中納入計費專案。要求中使用的專案必須記錄良好，且使用者在該專案中具備的角色必須擁有 serviceusage.services.use 權限。「服務使用情形消費者」角色包含必要權限。
  • 每個建議都需要特定權限。如要查看每個推薦工具的相關資訊 (包括必要權限) 連結表，請參閱「推薦工具」。

列出建議

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

如要使用正式發布的 GA 功能，您必須指定專案、位置和建議事項。詳情請參閱「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"

這項作業會以指定格式輸出目標專案中目前的 VM 執行個體大小建議，做為 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 是建議的專屬 ID

  • 與目前建議狀態相關聯的 etag 欄位。

使用後續 Google Cloud CLI 指令或 REST API 呼叫參照建議時，您會同時參照建議 ID 和 etag，確保只有在建議自上次擷取後未經修改時，才會執行任何作業。

變更建議的狀態

您可以將建議標示為已認領，表示您打算對相關聯的資源套用建議的變更。認領建議後，系統會將您的使用者名稱指派為建議的動作執行者，且 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 將建議標示為已關閉。
    • 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。