Menggunakan API - Rekomendasi

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

Interaksi rekomendasi standar dengan Recommender API adalah:

1. Mencantumkan rekomendasi untuk project tertentu.

2. Menandai rekomendasi yang ingin Anda terapkan sebagai claimed, atau menandai rekomendasi yang tidak ingin Anda terapkan sebagai dismissed.

3. Menerapkan rekomendasi. Anda dapat melakukannya secara otomatis menggunakan Active Assist di Google Cloud konsol, atau secara manual menggunakan perintah Google Cloud CLI, panggilan REST API, atau alat lainnya.

   Saat Anda menerapkan rekomendasi secara manual, perintah atau panggilan yang Anda gunakan khusus untuk jenis resource. Misalnya, untuk mengubah ukuran instance VM sebagai respons terhadap rekomendasi dari pemberi rekomendasi ukuran instance VM, Anda menggunakan perintah gcloud Compute Engine atau panggilan ke Compute Engine REST API.

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

   //API_NAME/RESOURCE_PATH

   Contoh:

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

4. Menandai rekomendasi sebagai succeeded atau failed.

Perhatikan bahwa hanya rekomendasi yang diambil melalui API yang dapat berinteraksi dengan menggunakan API atau Ekspor BigQuery.

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

Peringatan:

Sebelum menerapkan rekomendasi di konsol Google Cloud atau menggunakan API, pastikan dampak dinilai oleh peninjau dalam organisasi Anda. Peninjau harus memiliki pengetahuan untuk menilai dampak yang diidentifikasi dalam rekomendasi, serta dampak khusus terhadap infrastruktur dan bisnis Anda. Menerapkan rekomendasi tanpa penilaian yang tepat dapat menyebabkan perubahan yang tidak terduga, seperti masalah pada performa sistem, keandalan yang buruk, atau hilangnya izin yang diperlukan. Jika Anda memilih untuk menerapkan rekomendasi tanpa peninjauan oleh manusia, pastikan Anda telah menyiapkan proses rollback sebelum melakukan perubahan apa pun.

Menetapkan project default

Tetapkan project default jika Anda belum melakukannya:

gcloud config set project PROJECT_ID

dengan PROJECT_ID adalah ID project Anda.

Menetapkan variabel lingkungan

Tetapkan variabel lingkungan untuk interaksi Recommender:

PROJECT=TARGET_PROJECT_ID
LOCATION=LOCATION_ID
RECOMMENDER=RECOMMENDER_ID

dengan:

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

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

  Nomor project ditampilkan dalam respons dari perintah API dan gcloud.

• LOCATION_ID adalah Google Cloud lokasi tempat 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 Pemberi Rekomendasi untuk tabel link ke informasi tentang setiap pemberi rekomendasi, termasuk lokasi yang didukung dan ID pemberi 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 dengan izin serviceusage.services.use. Peran Konsumen Penggunaan Layanan memiliki izin yang diperlukan.
• Setiap pemberi rekomendasi memerlukan izin tertentu. Lihat Pemberi Rekomendasi untuk tabel link ke informasi tentang setiap pemberi rekomendasi, termasuk izin yang diperlukan.

Catatan: Jika Anda menggunakan header x-goog-user-project atau parameter string kueri userProject dalam permintaan Anda, Anda harus memiliki izin serviceusage.services.use untuk ID project yang Anda tentukan, selain izin IAM normal yang diperlukan untuk membuat permintaan.

Mencantumkan rekomendasi

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

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

gcloud Beta

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Masukkan:

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

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

Contoh:

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

Catatan: Tidak seperti output berikut untuk tab gcloud dan REST, yang terbatas pada rekomendasi untuk lokasi dan pemberi rekomendasi, output akan menyertakan semua rekomendasi untuk project.

gcloud

Masukkan:

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

dengan FORMAT adalah gcloud format output 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 menampilkan rekomendasi ukuran instance VM saat ini di project target sebagai daftar Recommendation entity 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 mencakup 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 Anda mereferensikan rekomendasi menggunakan perintah Google Cloud CLI berikutnya atau panggilan REST API, Anda mereferensikan ID rekomendasi dan etag, yang memastikan bahwa operasi apa pun hanya dilakukan jika rekomendasi belum diubah sejak terakhir kali Anda mengambilnya.

Mengubah status rekomendasi

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 tersebut, dan Recommender 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 Anda tidak ingin terus melihat rekomendasi tersebut. Jika rekomendasi ditolak, rekomendasi tersebut tidak akan lagi muncul sebagai rekomendasi AKTIF. Recommender mungkin akan terus memperbarui rekomendasi dengan konten yang lebih baru.

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

Untuk mengubah status rekomendasi, selesaikan langkah-langkah berikut:

gcloud

Masukkan:

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

Di mana

• STATE_CHANGE adalah perubahan yang ingin Anda lakukan pada rekomendasi. Nilai yang valid adalah:
  • mark-claimed untuk menandai rekomendasi sebagai diklaim.
  • mark-dismissed untuk menandai rekomendasi sebagai ditolak.
  • mark-succeeded untuk menandai rekomendasi sebagai berhasil.
  • mark-failed untuk menandai rekomendasi sebagai gagal.
• 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-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 yang 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 lakukan pada rekomendasi. Nilai yang valid adalah:
  • markClaimed untuk menandai rekomendasi sebagai diklaim.
  • markDismissed untuk menandai rekomendasi sebagai ditolak.
  • 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 Recommendation entity dalam format yang ditentukan setelah operasi terjadi.

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.