Menggunakan API - Insight

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

Interaksi insight umum dengan Recommender API adalah:

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

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

Tetapkan variabel lingkungan untuk interaksi Recommender:

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 berupa project yang berbeda dengan project Anda saat ini.

  • Untuk perintah gcloud, Anda harus menggunakan ID project
  • Untuk permintaan API, Anda dapat menggunakan nomor project atau ID project. Nomor project direkomendasikan.

  Nomor project ditampilkan dalam respons dari perintah API dan gcloud.

• LOCATION_ID adalah Google Cloud lokasi 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 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 dengan izin serviceusage.services.use. Peran Konsumen Service Usage memiliki izin yang diperlukan.
• Setiap jenis insight memerlukan izin tertentu. Lihat Jenis insight untuk 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 recommender. Fitur ini dalam versi Pratinjau.

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

gcloud Beta

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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 recommender, output 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 gcloud format output 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 menampilkan insight kebijakan IAM saat ini di project target sebagai daftar Insight entity 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 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 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 akan atau telah mengambil tindakan pada resource terkait berdasarkan informasi yang diberikan dalam insight. Saat insight diterima, nama pengguna Anda akan ditetapkan sebagai aktor untuk insight tersebut, dan Recommender 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 Insight entity 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.