Menggunakan API - Wawasan
Halaman ini menjelaskan cara melihat dan mengelola insight di Pemberi Rekomendasi menggunakan perintah gcloud
atau REST API.
Interaksi insight yang umum dengan Recommender API adalah:
- Daftar insight yang saat ini tersedia untuk jenis insight tertentu
- Tandai insight yang ingin Anda tindak lanjuti sebagai diterima
Untuk mengetahui informasi tentang cara mengubah status insight di Google Cloud Console, lihat dokumentasi untuk Hub Rekomendasi atau untuk jenis insight 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 Pemberi rekomendasi:
PROJECT=TARGET_PROJECT_ID LOCATION=LOCATION_ID INSIGHT_TYPE=INSIGHT_TYPE_ID
dengan:
TARGET_PROJECT_ID adalah project yang insight-nya ingin Anda cantumkan. Project ini bisa berbeda dari project Anda saat ini.
- Untuk perintah
gcloud
, Anda harus menggunakan project ID - Untuk permintaan API, Anda dapat menggunakan nomor project atau project ID. Sebaiknya gunakan nomor project.
Nomor project ditampilkan sebagai respons dari perintah API dan
gcloud
.- Untuk perintah
LOCATION_ID adalah lokasi Google Cloud tempat resource yang berkaitan dengan insight berada (misalnya,
global
atauus-central1-a
).INSIGHT_TYPE_ID adalah ID jenis insight yang sepenuhnya memenuhi syarat (misalnya,
google.iam.policy.Insight
).
Lihat Jenis insight untuk tabel link ke informasi tentang setiap jenis insight, termasuk lokasi yang didukung dan ID jenis insight.
Tetapkan izin
Anda harus memiliki izin untuk mengakses insight di project target.
- Untuk pemohon yang menyertakan project penagihan dalam permintaannya. Project
yang digunakan dalam permintaan harus memiliki reputasi baik, dan pengguna harus memiliki peran dalam
project yang berisi izin
serviceusage.services.use
. Peran Service Usage Consumer berisi izin yang diperlukan. - Setiap jenis insight memerlukan izin khusus. Lihat Jenis insight untuk melihat tabel link ke informasi tentang setiap jenis insight, termasuk izin yang diperlukan.
Membuat daftar insight
Untuk mencantumkan insight dalam project target:
gcloud
Masukkan:
gcloud recommender insights list \ --project=${PROJECT} \ --location=${LOCATION} \ --insight-type=${INSIGHT_TYPE} \ --format=FORMAT
dengan FORMAT adalah format output
gcloud
yang didukung (misalnya,
json
).
Contoh:
gcloud recommender insights list \ --project=example-project \ --location=global \ --insight-type=google.iam.policy.Insight \ --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}/insightTypes/${INSIGHT_TYPE}/insights"
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/insightTypes/google.iam.policy.Insight/insights"
Operasi ini menghasilkan insight kebijakan IAM saat ini dalam project target sebagai
daftar entity Insight
dalam
format yang ditentukan.
Outputnya mirip dengan hal berikut ini:
[ { "category": "SECURITY", "content": { "condition": { "description": "", "expression": "", "location": "", "title": "" }, "exercisedPermissions": [], "inferredPermissions": [], "member": "user:my-service-account@example-project.iam.gserviceaccount.com", "role": "roles/iam.securityReviewer" }, "description": "0 permission checks were authorized by this policy binding tuple.", "etag": "\"45f4e2c63f6952e8\"", "insightSubtype": "PERMISSIONS_USAGE", "lastRefreshTime": "2020-03-06T08:00:00Z", "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9", "observationPeriod": "7776000s", "stateInfo": { "state": "ACTIVE", }, "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/32428390823" ], } ]
Perhatikan bahwa insight yang ditampilkan mencakup kolom berikut:
Kolom
name
dalam format berikut:projects/PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID
tempat INSIGHT_ID mengidentifikasi insight secara unik
Kolom
etag
yang terkait dengan status insight saat ini.
Saat Anda mereferensikan insight menggunakan perintah gcloud
atau panggilan REST API berikutnya, Anda akan mereferensikan ID insight dan etag, yang memastikan bahwa operasi apa pun dilakukan hanya jika insight belum diubah sejak terakhir kali Anda mengambilnya.
Menandai insight sebagai diterima
Anda dapat menandai insight sebagai diterima untuk menunjukkan bahwa Anda bermaksud akan mengambil atau telah mengambil tindakan pada resource terkait berdasarkan informasi yang diberikan dalam insight. Saat insight diterima, nama pengguna Anda ditetapkan sebagai aktor untuk insight, dan Pemberi Rekomendasi tidak akan memperbarui insight dengan konten yang lebih baru.
Untuk menandai insight sebagai diterima:
gcloud
Masukkan:
gcloud recommender insights mark-accepted \ INSIGHT_ID \ --project=${PROJECT} \ --location=${LOCATION} \ --insight-type=${INSIGHT_TYPE} \ --etag=etag \ --state-metadata=STATE_METADATA --format=FORMAT
dengan:
- INSIGHT_ID adalah ID insight yang diambil dari panggilan sebelumnya untuk mencantumkan insight
- etag adalah etag yang ditampilkan yang mewakili status insight
- STATE_METADATA adalah metadata opsional tentang operasi tersebut. Tentukan metadata sebagai daftar yang dipisahkan koma untuk pasangan KEY=VALUE.
Contoh:
gcloud recommender insights mark-accepted \ a523ff7e-ed03-4143-a3a5-5b396b99cba9 \ --project=example-project \ --location=global \ --insight-type=google.iam.policy.Insight \ --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}/insightTypes/${INSIGHT_TYPE}/insights/INSIGHT_ID:markAccepted \ << EOM { "etag": "etag", "stateMetadata": STATE_METADATA } EOM
dengan:
- INSIGHT_ID adalah ID insight yang diambil dari panggilan sebelumnya untuk mencantumkan insight
- etag adalah etag yang ditampilkan yang mewakili status insight
- STATE_METADATA adalah kolom opsional dengan metadata tambahan tentang operasi. Tentukan metadata sebagai pasangan
key:value
.
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/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9:markAccepted \ << EOM { "etag": "\"280b34810bba8a1a\"" "stateMetadata": { "priority" : "high", "tracking_number": "12345" } } EOM
Operasi ini menampilkan entity Insight
dalam format yang ditentukan setelah operasi berlangsung.
Outputnya mirip dengan hal berikut ini:
{ "category": "SECURITY", "content": { ... }, "description": "0 permission checks were authorized by this policy binding tuple.", "etag": "\"356ae51165729f38\"", "insightSubtype": "PERMISSIONS_USAGE", "lastModifiedUser": "admin123@example-project.iam.gserviceaccount.com", "lastRefreshTime": "2020-03-06T08:00:00Z", "name": "projects/32428390823/locations/global/insightTypes/google.iam.policy.Insight/insights/a523ff7e-ed03-4143-a3a5-5b396b99cba9", "observationPeriod": "7776000s", "stateInfo": { "state": "ACCEPTED", "stateMetadata": { "priority" : "high", "tracking_number": "12345" } }, "targetResources": [ "//cloudresourcemanager.googleapis.com/projects/32428390823" ], "userLastUpdateTime": "2020-03-31T20:57:50.509855Z" }
Perhatikan bahwa nilai kolom state
telah diubah menjadi ACCEPTED
.