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.

  • LOCATION_ID adalah lokasi Google Cloud tempat resource yang berkaitan 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.

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.