Menggunakan API - Insight

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
  • Menandai insight yang ingin ditindaklanjuti sebagai diterima

Untuk mengetahui informasi tentang cara mengubah status insight di Konsol Google Cloud, lihat dokumentasi untuk Hub Rekomendasi atau 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 jadi 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. Nomor project direkomendasikan.

    Nomor project ditampilkan sebagai respons dari perintah API dan gcloud.

  • LOCATION_ID adalah lokasi Google Cloud tempat 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 melihat 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 dalam 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 membuat daftar 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 secara unik mengidentifikasi insight

  • Kolom etag yang terkait dengan status insight saat ini.

Saat mereferensikan insight menggunakan perintah gcloud berikutnya atau panggilan REST API, Anda mereferensikan ID insight dan etag, yang memastikan bahwa operasi apa pun hanya dilakukan jika insight belum diubah sejak terakhir kali Anda 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 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 membuat daftar insight
  • etag adalah etag yang ditampilkan yang mewakili status insight
  • STATE_METADATA adalah metadata opsional tentang operasi. 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 membuat daftar 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 berubah menjadi ACCEPTED.