Menggunakan API - Insight

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

Interaksi insight umum dengan Recommender API adalah:

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

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

Menetapkan variabel lingkungan

Menetapkan 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 buat daftarnya. 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 ID project. Sebaiknya gunakan nomor project.

  Nomor project ditampilkan dalam respons dari API dan perintah 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 memenuhi syarat sepenuhnya (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 dalam project target.

• Untuk pemohon yang menyertakan project penagihan dalam permintaannya. Project yang digunakan dalam permintaan harus bereputasi baik, dan pengguna harus memiliki peran dalam project dengan izin serviceusage.services.use. Peran Service Usage Consumer 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.

Mencantumkan insight

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

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

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

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

gcloud recommender insights list \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --format=FORMAT

gcloud recommender insights list \
    --project=example-project \
    --location=global \
    --insight-type=google.iam.policy.Insight \
    --format=json

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"

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: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

  dengan INSIGHT_ID mengidentifikasi insight secara unik

• 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 dimodifikasi sejak terakhir kali Anda mengambilnya.

Menandai insight sebagai diterima

Anda dapat menandai analisis sebagai diterima untuk menunjukkan bahwa Anda bermaksud mengambil atau telah mengambil tindakan pada aset terkait berdasarkan informasi yang diberikan dalam analisis. Saat insight diterima, nama pengguna Anda ditetapkan sebagai aktor untuk insight tersebut, dan Recommender tidak akan memperbarui insight dengan konten yang lebih baru.

Untuk menandai insight sebagai diterima:

gcloud recommender insights mark-accepted \
    INSIGHT_ID \
    --project=${PROJECT} \
    --location=${LOCATION} \
    --insight-type=${INSIGHT_TYPE} \
    --etag=etag \
    --state-metadata=STATE_METADATA
    --format=FORMAT

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

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

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 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": "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.