本頁面由 Cloud Translation API 翻譯而成。

使用 API - 建議內容

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

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

列出特定專案的建議。
將要套用的最佳化建議標示為「已套用」，或將不要套用的最佳化建議標示為「已略過」。
使用 gcloud 指令或 REST API 呼叫，套用建議，這些指令或呼叫會專門針對資源類型 (例如 IAM 角色或 Compute Engine VM 執行個體)。
將建議標示為成功或失敗。

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

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

設定預設專案

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

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，將建議標示為已關閉。
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 呼叫 (特定於資源類型) 套用建議。

舉例來說，如要根據 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"

變更建議的狀態

套用建議後，您可以將其標示為成功或失敗。

如要將建議標示為成功，請按照下列步驟操作：

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

地點

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。