Menggunakan API - Insight

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

Catatan: Beberapa perekomendasikan tidak mendukung penggunaan REST API atau gcloud CLI untuk melihat dan mengelola rekomendasi dan insight. Untuk mengetahui detail tentang pemberi rekomendasi dan klien yang didukung, lihat Pemberi rekomendasi.

Interaksi insight standar dengan Recommender API adalah:

• Mencantumkan insight untuk project tertentu
• Menandai insight yang ingin Anda tindak lanjuti sebagai diterima

Untuk mengetahui informasi tentang cara mengubah status insight di konsol Google Cloud, lihat dokumentasi untuk Recommendation Hub 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 project ID Anda.

Menetapkan variabel lingkungan

Tetapkan variabel lingkungan untuk interaksi 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 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 insight berada (misalnya, global atau us-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.

Menetapkan 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 bereputasi baik, dan penggunanya harus memiliki peran dalam project yang berisi izin serviceusage.services.use. Peran Konsumen Penggunaan Layanan memiliki izin yang diperlukan.
• Setiap jenis insight memerlukan izin tertentu. Lihat Jenis insight untuk melihat tabel link ke informasi tentang setiap jenis insight, 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 insight

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

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

gcloud Beta

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Masukkan:

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

dengan FORMAT adalah format output Google Cloud CLI yang didukung, seperti json.

Contoh:

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

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

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 di project target sebagai daftar entitas Insight dalam format yang ditentukan.

Outputnya mirip dengan hal berikut ini:

[
  {
    "category": "SECURITY",
    "content": {
      "condition": {
        "description": "",
        "expression": "",
        "location": "",
        "title": ""
      },
      "exercisedPermissions": [],
      "inferredPermissions": [],
      "member": "user:[e-mail]",
      "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

  dengan INSIGHT_ID secara unik mengidentifikasi insight

• Kolom etag yang terkait dengan status insight saat ini.

Saat mereferensikan insight menggunakan perintah gcloud atau panggilan REST API berikutnya, Anda mereferensikan ID insight dan etag, yang memastikan bahwa operasi hanya dilakukan jika insight belum diubah sejak Anda terakhir kali mengambilnya.

Menandai insight sebagai diterima

Anda dapat menandai insight sebagai diterima untuk menunjukkan bahwa Anda bermaksud mengambil atau telah mengambil tindakan pada resource terkait berdasarkan informasi yang diberikan dalam insight. Saat insight diterima, nama pengguna Anda akan ditetapkan sebagai pelaku untuk insight tersebut, dan 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. Tentukan metadata sebagai daftar pasangan KEY=VALUE yang dipisahkan koma.

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 entitas Insight dalam format yang ditentukan setelah operasi dilakukan.

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": "[e-mail]",
  "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 berubah menjadi ACCEPTED.