API の使用 - 推奨事項

このページでは、gcloud コマンドや REST API を使用して、Recommender の推奨事項を表示、管理する方法について説明します。

Recommender API でよく行われる推奨事項の操作は、次のようなものです。

特定の Recommender について利用可能な推奨事項を一覧表示する
適用する推奨事項を申請済みとしてマークするか、適用しない推奨事項を拒否済みとしてマークする
リソースタイプ（IAM ロールや Compute Engine VM インスタンスなど）に固有の gcloud コマンドや REST API 呼び出しを使用して、推奨事項を適用する
推奨事項を成功または失敗としてマークする

API を介して取得した推奨事項は、API または BigQuery Export を介してのみ操作できます。

Google Cloud コンソールで推奨事項の状態を変更する方法については、おすすめハブのドキュメントか、適切な 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 の ID など、各 Recommender に関する情報へのリンクの表については、Recommender をご覧ください。

権限の設定

ターゲットプロジェクトの推奨事項にアクセスするには、権限が必要です。

リクエストに請求先プロジェクトが含まれるリクエスト元の場合。リクエストで使用されるプロジェクトは良好な状態でなければなりません。また、serviceusage.services.use 権限を含むプロジェクト内のロールがユーザーに付与されている必要があります。必要な権限は、Service Usage ユーザーロールに含まれています。
各 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"

このオペレーションにより、ターゲットプロジェクトの現在の 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 により一意に識別されます。
現在の推奨事項の状態に関連付けられている 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 呼び出しを使用して、推奨事項を適用できます。

たとえば、VM インスタンスのサイズを変更する Recommender が提案した推奨事項に対応して 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 に変更されています。

API の使用 - 推奨事項

デフォルト プロジェクトの設定

環境変数の設定

権限の設定

推奨事項の一覧表示

gcloud

REST

推奨事項を申請済みまたは拒否済みとしてマークする

gcloud

REST

推奨事項を適用する

推奨事項の状態を変更する

gcloud

REST

デフォルトプロジェクトの設定