Menggunakan API - Rekomendasi

Halaman ini menjelaskan cara melihat dan mengelola rekomendasi di Recommender menggunakan perintah gcloud atau REST API.

Interaksi rekomendasi standar dengan Recommender API adalah:

  • Mencantumkan rekomendasi untuk project tertentu.
  • Tandai rekomendasi yang ingin Anda terapkan sebagai diklaim, atau tandai rekomendasi yang tidak ingin Anda terapkan sebagai ditolak.
  • Terapkan rekomendasi menggunakan perintah gcloud atau panggilan REST API khusus untuk jenis resource (misalnya, peran IAM atau instance VM Compute Engine).
  • Tandai rekomendasi sebagai berhasil atau gagal.

Perhatikan bahwa hanya rekomendasi yang diambil melalui API yang dapat berinteraksi melalui API atau BigQuery Export.

Untuk mengetahui informasi tentang cara mengubah status rekomendasi di konsol Google Cloud , lihat dokumentasi untuk Recommendation Hub atau untuk rekomendasi yang sesuai.

Menetapkan project default

Tetapkan project default jika Anda belum melakukannya:

gcloud config set project PROJECT_ID

dengan PROJECT_ID sebagai ID project Anda.

Menetapkan variabel lingkungan

Tetapkan variabel lingkungan untuk interaksi Rekomendasi:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

dengan:

  • TARGET_PROJECT_ID adalah project yang rekomendasinya ingin Anda cantumkan. Project ini dapat berbeda dengan project Anda saat ini.

    • Untuk perintah gcloud, Anda harus menggunakan project ID
    • Untuk permintaan API, Anda dapat menggunakan nomor project atau project ID. Sebaiknya masukkan nomor project.

    Nomor project ditampilkan dalam respons dari perintah API dan gcloud.

  • LOCATION_ID adalah lokasi Google Cloudtempat resource yang terkait dengan rekomendasi berada (misalnya, global atau us-central1-a).

  • RECOMMENDER_ID adalah ID pemberi rekomendasi yang sepenuhnya memenuhi syarat (misalnya, google.compute.instance.MachineTypeRecommender).

Lihat Rekomendasi untuk melihat tabel link ke informasi tentang setiap rekomendasi, termasuk lokasi yang didukung dan ID rekomendasi.

Menetapkan izin

Anda harus memiliki izin untuk mengakses rekomendasi di project target.

  • Untuk pemohon yang menyertakan project penagihan dalam permintaannya. Project yang digunakan dalam permintaan harus bereputasi baik, dan penggunanya harus memiliki peran dalam project yang berisi izin serviceusage.services.use. Peran Konsumen Penggunaan Layanan memiliki izin yang diperlukan.
  • Setiap perekomendasikan memerlukan izin tertentu. Lihat Rekomendasi untuk melihat tabel link ke informasi tentang setiap rekomendasi, termasuk izin yang diperlukan.

Membuat daftar rekomendasi

Seperti yang ditunjukkan di tab gcloud Beta, Anda dapat mencantumkan semua rekomendasi project tanpa harus menentukan lokasi dan perekomendasikan. Fitur ini dalam Pratinjau.

Fitur GA mengharuskan Anda menentukan project, lokasi, dan perekomendasikan. Untuk mengetahui detailnya, lihat tab gcloud.

gcloud Beta

Masukkan:

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

dengan FORMAT adalah format output gcloud yang didukung, seperti json.

Contoh:

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

gcloud

Masukkan:

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

dengan FORMAT adalah format output gcloud yang didukung (misalnya, json).

Contoh:

gcloud recommender recommendations list \
    --project=example-project \
    --location=us-central1-a \
    --recommender=google.compute.instance.MachineTypeRecommender \
    --format=json

REST

Masukkan:

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"

Contoh:

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"

Operasi ini menghasilkan rekomendasi ukuran instance VM saat ini dalam project target sebagai daftar entitas Recommendation dalam format yang ditentukan.

Outputnya mirip dengan hal berikut ini:

[
  {
    "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"
  }
]

Perhatikan bahwa rekomendasi yang ditampilkan menyertakan kolom berikut:

  • Kolom name dalam format berikut:

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

    dengan RECOMMENDATION_ID mengidentifikasi rekomendasi secara unik

  • Kolom etag yang terkait dengan status rekomendasi saat ini.

Saat mereferensikan rekomendasi menggunakan perintah Google Cloud CLI atau panggilan REST API berikutnya, Anda mereferensikan ID dan etag rekomendasi, yang memastikan bahwa operasi hanya dilakukan jika rekomendasi belum diubah sejak Anda terakhir mengambilnya.

Menandai rekomendasi sebagai diklaim atau ditolak

Anda dapat menandai rekomendasi sebagai diklaim untuk menunjukkan bahwa Anda ingin menerapkan perubahan yang direkomendasikan ke resource terkait. Saat rekomendasi diklaim, nama pengguna Anda ditetapkan sebagai aktor untuk rekomendasi, dan Rekomendasi tidak memperbarui rekomendasi dengan konten yang lebih baru.

Anda dapat menandai rekomendasi sebagai ditolak untuk menunjukkan bahwa Anda tidak ingin menerapkan perubahan yang direkomendasikan ke resource terkait atau bahwa Anda tidak ingin terus melihat rekomendasi tersebut. Jika ditutup, rekomendasi tidak akan muncul lagi sebagai rekomendasi AKTIF. Rekomendator dapat terus memperbarui rekomendasi dengan konten yang lebih baru.

Untuk menandai rekomendasi sebagai diklaim atau ditolak:

gcloud

Masukkan:

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

Dengan keterangan:

  • STATE_CHANGE adalah status yang ingin Anda tandai ke rekomendasi. Nilai yang valid adalah:
    • mark-claimed untuk menandai rekomendasi sebagai diklaim.
    • mark-dismissed untuk menandai rekomendasi sebagai ditolak.
  • RECOMMENDATION_ID adalah ID rekomendasi yang Anda ambil dari panggilan sebelumnya untuk mencantumkan rekomendasi
  • etag adalah etag yang ditampilkan yang mewakili status rekomendasi
  • STATE_METADATA adalah metadata opsional tentang operasi. Tentukan metadata sebagai daftar pasangan KEY=VALUE yang dipisahkan koma. Opsi ini tersedia saat Anda menandai rekomendasi sebagai diklaim, berhasil, atau gagal.

Contoh:

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

Masukkan:

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

dengan:

  • STATE_CHANGE adalah status yang ingin Anda tandai ke rekomendasi. Nilai yang valid adalah:
    • mark-claimed untuk menandai rekomendasi sebagai diklaim.
    • mark-dismissed untuk menandai rekomendasi sebagai ditolak.
  • RECOMMENDATION_ID adalah ID rekomendasi yang Anda ambil dari panggilan sebelumnya untuk mencantumkan rekomendasi
  • etag adalah etag yang ditampilkan yang mewakili status rekomendasi
  • STATE_METADATA adalah kolom opsional dengan metadata tambahan tentang operasi. Tentukan metadata sebagai pasangan key:value. Kolom ini tersedia saat Anda menandai rekomendasi sebagai diklaim, berhasil, atau gagal.

Contoh:

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

Operasi ini menampilkan entitas Recommendation dalam format yang ditentukan setelah operasi dilakukan.

Outputnya mirip dengan hal berikut ini:

{
  "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"
  }
}

Perhatikan bahwa nilai kolom state telah berubah menjadi CLAIMED.

Menerapkan rekomendasi

Setelah menandai rekomendasi sebagai diklaim, Anda dapat menerapkan rekomendasi menggunakan perintah gcloud atau panggilan REST API yang khusus untuk jenis resource.

Misalnya, untuk mengubah ukuran instance VM sebagai respons terhadap rekomendasi dari pemberi rekomendasi penentuan ukuran instance VM, Anda menggunakan perintah gcloud Compute Engine atau panggilan ke REST API Compute Engine.

Saat melakukan operasi ini, Anda mengidentifikasi resource target menggunakan nilai kolom resource dalam array OperationsGroup dalam entity Recommendation yang ditampilkan. Kolom ini memiliki format berikut:

//API_NAME/RESOURCE_PATH

Contoh:

//compute.googleapis.com/projects/example-project/zones/us-central1-a/instances/instance-1"

Mengubah status rekomendasi

Setelah menerapkan rekomendasi, Anda dapat menandainya sebagai berhasil atau gagal.

Untuk menandai rekomendasi sebagai berhasil:

gcloud

Masukkan:

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

Dari mana

  • STATE_CHANGE adalah perubahan yang ingin Anda buat pada rekomendasi. Nilai yang valid adalah:
    • mark-succeeded untuk menandai rekomendasi sebagai berhasil.
    • mark-failed untuk menandai rekomendasi sebagai gagal.
  • STATE_METADATA adalah metadata opsional tentang operasi. Tentukan metadata sebagai daftar pasangan KEY=VALUE yang dipisahkan umum. Opsi ini tersedia saat Anda menandai rekomendasi sebagai diklaim, berhasil, atau gagal.

Contoh:

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

Masukkan kode berikut

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

dengan:

  • RECOMMENDATION_ID adalah ID rekomendasi yang Anda ambil dari panggilan sebelumnya untuk mencantumkan rekomendasi
  • STATE_CHANGE adalah perubahan yang ingin Anda buat pada rekomendasi. Nilai yang valid adalah:
    • markSucceeded untuk menandai rekomendasi sebagai berhasil.
    • markFailed untuk menandai rekomendasi sebagai gagal.
  • etag adalah etag yang ditampilkan yang mewakili status rekomendasi
  • STATE_METADATA adalah kolom opsional dengan metadata tambahan tentang operasi. Tentukan metadata sebagai pasangan key:value. Kolom ini tersedia saat Anda menandai rekomendasi sebagai diklaim, berhasil, atau gagal.

Contoh:

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

Operasi ini menampilkan entitas Recommendation dalam format yang ditentukan setelah operasi dilakukan.

Outputnya mirip dengan hal berikut ini:

{
  "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"
    }
  }
}

Perhatikan bahwa nilai kolom state telah berubah menjadi SUCCEEDED.