Menggunakan API - Rekomendasi
Halaman ini menjelaskan cara melihat dan mengelola
rekomendasi di Recommender menggunakan
perintah gcloud
atau
REST API.
Interaksi rekomendasi umum dengan Recommender API adalah:
- Mencantumkan rekomendasi untuk project tertentu.
- Tandai rekomendasi yang akan Anda terapkan sebagai diklaim, atau tandai rekomendasi yang tidak akan 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 digunakan melalui API atau BigQuery Export.
Untuk mengetahui informasi tentang cara mengubah status rekomendasi di Google Cloud konsol, lihat dokumentasi untuk Recommendation Hub atau untuk pemberi rekomendasi yang sesuai.
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
Menetapkan 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 tampilkan dalam daftar. 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 ID project. Sebaiknya gunakan nomor project.
Nomor project ditampilkan dalam respons dari API dan perintah
gcloud
.- Untuk perintah
LOCATION_ID adalah Google Cloud lokasi tempat resource yang terkait dengan rekomendasi berada (misalnya,
global
atauus-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 pengguna harus memiliki peran dalam
project dengan izin
serviceusage.services.use
. Peran Service Usage Consumer memiliki izin yang diperlukan. - Setiap pemberi rekomendasi memerlukan izin tertentu. Lihat Pemberi rekomendasi untuk melihat tabel link ke informasi tentang setiap pemberi rekomendasi, termasuk izin yang diperlukan.
Daftar rekomendasi
Seperti yang ditunjukkan di tab gcloud Beta, Anda dapat mencantumkan semua rekomendasi project tanpa harus menentukan lokasi dan pemberi rekomendasi. Fitur ini dalam Pratinjau.
Fitur GA mengharuskan Anda menentukan project, lokasi, dan pemberi rekomendasi. 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 menampilkan 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 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.
Menandai rekomendasi sebagai diklaim atau ditolak
Anda dapat menandai rekomendasi sebagai diklaim untuk menunjukkan bahwa Anda bermaksud menerapkan perubahan yang direkomendasikan pada resource terkait. Saat rekomendasi diklaim, nama pengguna Anda ditetapkan sebagai aktor untuk rekomendasi, dan Recommender tidak memperbarui rekomendasi dengan konten yang lebih baru.
Anda dapat menandai rekomendasi sebagai ditolak untuk menunjukkan bahwa Anda tidak berniat menerapkan perubahan yang direkomendasikan ke resource terkait atau bahwa Anda tidak ingin terus melihat rekomendasi tersebut. Jika ditutup, rekomendasi tidak akan lagi muncul sebagai rekomendasi AKTIF. Recommender dapat terus memperbarui rekomendasi dengan konten yang lebih baru.
Untuk menandai rekomendasi sebagai sudah 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:
- STATE_CHANGE adalah status yang ingin Anda tandai untuk rekomendasi.
Nilai yang valid adalah:
mark-claimed
untuk menandai rekomendasi sebagai sudah 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 untuk rekomendasi.
Nilai yang valid adalah:
mark-claimed
untuk menandai rekomendasi sebagai sudah 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 merepresentasikan 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 entity
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
di 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
Di mana
- STATE_CHANGE adalah perubahan yang ingin Anda lakukan 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 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 ini
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:
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 entity
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
.