Mengembangkan solusi platform grafik kustom

Note

Fitur ini masih dalam mode pratinjau. Lihat Ketentuan Penggunaan Tambahan untuk Pratinjau Microsoft Azure.

Solusi grafik kustom Microsoft Sentinel adalah solusi berbasis buku catatan yang menentukan simpul dan tepi dari tabel data lake Microsoft Sentinel, membangun grafik, dan memungkinkan pengguna mengkueri grafik tersebut dengan Graph Query Language (GQL).

Gunakan panduan ini untuk membangun, menguji, mewujudkan, mengemas, dan menerbitkan solusi grafik kustom sebagai penawaran SaaS di Pusat Mitra Microsoft sehingga pelanggan dapat menemukannya di Microsoft Security Store.

Prasyarat

Anda harus terdaftar di data lake untuk membuat solusi Custom Graph. Untuk informasi selengkapnya, lihat Cara onboarding ke data lake Microsoft Sentinel.

Permissions

Tabel berikut mencantumkan izin yang diperlukan untuk setiap operasi atau cakupan dalam panduan ini.

Operation	Peran yang diperlukan
Orientasi untuk data lake Sentinel	Microsoft Entra ID - Administrator Keamanan atau Administrator Global
Sertakan ruang kerja Sentinel ke portal Defender	Pemilik Langganan, atau Administrator Akses Pengguna pada cakupan langganan dan Kontributor Microsoft Sentinel pada cakupan langganan atau grup sumber daya
Gabungkan ruang kerja Sentinel ke data lake	Pemilik Langganan atau Kontributor Microsoft Sentinel pada cakupan langganan atau grup sumber daya
Memodelkan dan membuat grafik buku catatan	Peran RBAC terpadu Microsoft Defender XDR kustom dengan izin `data (manage)` untuk pengumpulan data Microsoft Sentinel
Mempertahankan (mewujudkan) grafik	Operator Keamanan, Administrator Keamanan, atau Administrator Global
Melakukan kueri pada graf yang dipertahankan	Peran RBAC terpadu Microsoft Defender XDR kustom dengan `security data basics (read)` atas pengumpulan data Microsoft Sentinel
Menerbitkan solusi Grafik Kustom	Akun Publisher marketplace di Pusat Mitra Microsoft

Tools

Alat berikut diperlukan untuk membangun dan menerbitkan solusi grafik kustom:

Visual Studio Code.
ekstensi Microsoft Sentinel untuk Visual Studio Code. Untuk informasi lebih lanjut, lihat Instal Visual Studio Code dan ekstensi Microsoft Sentinel.
Ekstensi Jupyter untuk Visual Studio Code.
GitHub Copilot ekstensi dan paket GitHub Copilot Business atau Enterprise.
Python 3.10 atau yang lebih baru di komputer lokal Anda.

Tip

Gunakan kembali data lake yang sudah ada jika tenant Anda sudah diaktifkan untuk kueri KQL, notebook, atau agen Security Copilot. Ada satu data lake per tenant. Di portal Defender, buka Sistem>Pengaturan>Microsoft Sentinel>Data lake. Jika status adalah Tersedia, lewati tugas 1.

Alur kerja build

Alur kerja berikut menguraikan langkah-langkah untuk membangun dan menerbitkan solusi grafik kustom.

Masukkan data sampel ke dalam tabel yang dimodelkan oleh graf Anda.
Validasi konektivitas dengan notebook sederhana.
Buat grafik kustom.
Uji buku catatan grafik.
Jadwalkan tugas grafik untuk membentuk grafik.
Mengkueri dan memvisualisasikan grafik dari penjelajah Graph.
Mengemas dan menerbitkan solusi grafik kustom.

Memasukkan data sampel

Tugas ini memproses tabel aset Microsoft Entra ID yang digunakan oleh grafik contoh dalam panduan ini: EntraUsers, EntraGroups, EntraServicePrincipals, dan EntraMembers.

Di portal Defender, bukaPengaturan>Sistem>Microsoft Sentinel>Konektor data.
Aktifkan konektor Microsoft Entra ID sehingga tabel aset Entra diserap ke dalam data lake. Untuk informasi lebih lanjut, lihat Data aset di danau data Microsoft Sentinel.
Konfirmasikan tabel ini muncul di data lake explorer:
- EntraUsers
- EntraGroups
- EntraServicePrincipals
- EntraMembers
Tabel-tabel ini berada di ruang kerja System tables.
Opsional: menyerap konektor lain dan mengganti nama tabel di langkah selanjutnya jika skenario Anda menggunakan data yang berbeda.

Note

Jika tabel tidak muncul di data lake explorer, Anda tidak dapat menggunakannya untuk penulisan grafik, dan bantuan AI tidak akan mereferensikannya.

Memvalidasi konektivitas dengan notebook sederhana

Buat dan jalankan notebook minimal untuk memverifikasi konektivitas data lake sebelum penulisan grafik.

Buka Visual Studio Code dan masuk ke ekstensi Microsoft Sentinel dengan akun yang sama yang memiliki akses ke data lake.
Di Visual Studio Code, di bawah Ekstensi Sentinel–Grafik pilih Buat buku catatan baru.
Simpan buku catatan, misalnya hello-world-show-tables.ipynb.
Pilih Pilih kernel, pilih Microsoft Sentinel, dan pilih kumpulan Spark yang tersedia.
Tambahkan sel berikut secara berurutan.

Sel 1 - Markdown:

# Hello World: Show Tables
A minimal connectivity test for the Microsoft Sentinel data lake.
If every cell below runs without error, your environment is ready
to author custom graphs.
Steps:
1. Connect to the data lake with the Microsoft Sentinel provider
2. Point at your workspace
3. Read a table and show a few rows

Sel 2 - Kode (sambungkan dan atur ruang kerja Anda):

from sentinel_lake.providers import MicrosoftSentinelProvider
# The provider gives the notebook access to data lake tables.
lake_provider = MicrosoftSentinelProvider(spark=spark)
# >>> ADD YOUR WORKSPACE HERE <<<
# Replace with the Log Analytics workspace that holds your tables.
# Entra asset tables (EntraUsers, EntraGroups, ...) live in "System tables".
LOG_ANALYTICS_WORKSPACE = "System tables"
print(f"Using workspace: {LOG_ANALYTICS_WORKSPACE}")

Sel 3 - Markdown:

## Read a table and show rows
Reading a known table is the fastest way to confirm the extension
can reach the lake with your permissions. Swap EntraGroups for any
table that exists in your workspace.

Sel 4 - Kode (baca tabel dan perlihatkan baris):

# Read a table from the data lake into a Spark DataFrame.
df_groups = lake_provider.read_table("EntraGroups", LOG_ANALYTICS_WORKSPACE)
# Show a sample. .df exposes the underlying Spark DataFrame.
df_groups.df.select("id", "displayName", "mailEnabled").show(20, truncate=False)

Sel 5 - Kode (pemeriksaan kewajaran opsional):

# Confirm the read returned data and inspect the schema.
print("Row count:", df_groups.df.count())
df_groups.df.printSchema()

Jalankan semua sel dari atas ke bawah.
Konfirmasikan setiap sel selesai tanpa pelacakan balik merah, data pratinjau tabel muncul, dan jumlah baris bukan nol.

Note

Jika pembacaan gagal atau tidak mengembalikan baris, pastikan konektor dari bagian Mengimpor data sampel telah menyelesaikan snapshot pertamanya, LOG_ANALYTICS_WORKSPACE mengacu pada workspace yang benar-benar ada, dan akun Anda memiliki izin baca. Periksa konten tabel dengan KQL di portal Defender untuk mengonfirmasi adanya data. Untuk informasi selengkapnya, lihat Menjalankan kueri KQL di data lake Microsoft Sentinel.

Buat grafik kustom

Penulis dengan salah satu cara berikut:

Penulisan grafik yang dibantu AI.
Tulis dengan tangan.

Penulisan grafik yang dibantu AI

Untuk menulis grafik dengan bantuan AI, ikuti langkah-langkah berikut:

Di Visual Studio Code, buka GitHub Copilot Chat.

Mulai perintah Anda dengan pembantu @sentinel /graph-authoring penulisan grafik dan jelaskan grafik Anda dalam bahasa biasa:

@sentinel /graph-authoring Create a graph that maps Entra groups to
their member users, groups, and service principals using EntraGroups,
EntraUsers, EntraServicePrincipals, and EntraMembers from the
"System tables" workspace.

Copilot menghasilkan sel berikut untuk siklus hidup penulisan grafik:

Tahap siklus hidup	Output yang dihasilkan
Pengaturan lingkungan	Memverifikasi paket dan informasi koneksi yang diperlukan
Pemuatan data	Membaca tabel berdasarkan nama dari data lake Sentinel
Transformasi data	Menyiapkan data simpul dan tepi
Skema grafik	Mendefinisikan simpul dan tepi
Skema validasi	Memvalidasi definisi graf
Membangun grafik	Mewujudkan grafik untuk sesi
Kueri graf	Menjalankan sampel kueri GQL dan memvisualisasikan hasilnya

Lanjutkan menyempurnakan buku catatan dengan perintah seperti ini:

Tujuan	Prompt
Menambah relasi	`@sentinel Add an edge from User to IPAddress`
Penyaringan data	`@sentinel Filter the data to show only failed sign-ins`
Ubah rentang waktu	`@sentinel Change the time range to the last 7 days`
Memperbaiki kesalahan build	`@sentinel Fix the error in the graph build step`
Memahami kode	`@sentinel Explain how edge keys are defined`
Mencari API tanpa mengedit	`What parameters does build_graph_with_data() accept? #Sentinel`

Tip

Gunakan @sentinel /graph-authoring untuk membuat atau mengubah sel buku catatan. Jika Anda memerlukan penjelasan API atau kueri sampel, tanyakan Copilot dan sertakan #Sentinel untuk jawaban khusus Sentinel.

Tulis secara manual

Untuk menulis grafik secara manual, ikuti langkah-langkah berikut:

Hubungkan dan baca tabel aset.

from pyspark.sql import functions as F
from sentinel_lake.providers import MicrosoftSentinelProvider
lake_provider = MicrosoftSentinelProvider(spark=spark)
# Entra asset tables live in the "System tables" workspace.
# If your data is elsewhere, update this and ensure the tables exist.
LOG_ANALYTICS_WORKSPACE = "System tables"
# Use the latest snapshot of EntraUsers as the point-in-time for all tables.
snapshot_time = (
    lake_provider.read_table("EntraUsers", LOG_ANALYTICS_WORKSPACE)
    .df.agg(F.max("_SnapshotTime").alias("max_snapshot"))
    .collect()[0]["max_snapshot"]
    .strftime("%Y-%m-%dT%H:%M:%SZ")
)
print(f"Using snapshot_time: {snapshot_time}")
snapshot_filter = (F.col("_SnapshotTime") == F.lit(snapshot_time).cast("timestamp"))
# Edges: group contains user / group / servicePrincipal
df_members = (
    lake_provider.read_table("EntraMembers", LOG_ANALYTICS_WORKSPACE)
    .filter(
        snapshot_filter
        & (F.col("sourceType") == "group")
        & (F.col("targetType").isin("user", "group", "servicePrincipal"))
    )
)
# Nodes
df_groups = (
    lake_provider.read_table("EntraGroups", LOG_ANALYTICS_WORKSPACE)
    .filter(snapshot_filter)
    .select("id", "displayName", "mailEnabled")
)
df_users = (
    lake_provider.read_table("EntraUsers", LOG_ANALYTICS_WORKSPACE)
    .filter(snapshot_filter)
    .select("id", "accountEnabled", "displayName", "department",
            "userPrincipalName", "usageLocation")
)

Siapkan node dan edge DataFrames.

# NODES
user_nodes = df_users.df.select(
    "id", "displayName", "accountEnabled", "department",
    "userPrincipalName", "usageLocation")
group_nodes = df_groups.df.select("id", "displayName", "mailEnabled")
# EDGES
edge_group_contains_user = (
    df_members.df.filter(F.col("targetType") == "user")
    .select(F.col("sourceId").alias("SourceGroupId"),
            F.col("targetId").alias("TargetUserId"))
    .distinct()
    .withColumn("EdgeKey", F.concat_ws("_", F.col("SourceGroupId"), F.col("TargetUserId")))
)
edge_group_contains_group = (
    df_members.df.filter(F.col("targetType") == "group")
    .select(F.col("sourceId").alias("SourceGroupId"),
            F.col("targetId").alias("TargetGroupId"))
    .distinct()
    .withColumn("EdgeKey", F.concat_ws("_", F.col("SourceGroupId"), F.col("TargetGroupId")))
)

Tentukan skema graf dan ikatkan DataFrames.

from sentinel_graph import GraphSpecBuilder, Graph
entra_group_graph_spec = (
    GraphSpecBuilder.start()
    # === NODES ===
    .add_node("EntraUser").from_dataframe(user_nodes)
    .with_columns("id", "displayName", "accountEnabled", "department",
                  "userPrincipalName", "usageLocation",
                  key="id", display="displayName")
    .add_node("EntraGroup").from_dataframe(group_nodes)
    .with_columns("id", "displayName", "mailEnabled",
                  key="id", display="displayName")
    # === EDGES ===
    .add_edge("ContainsUser").from_dataframe(edge_group_contains_user)
    .source(id_column="SourceGroupId", node_type="EntraGroup")
    .target(id_column="TargetUserId", node_type="EntraUser")
    .with_columns("SourceGroupId", "TargetUserId", "EdgeKey",
                  key="EdgeKey", display="EdgeKey")
    .add_edge("ContainsGroup").from_dataframe(edge_group_contains_group)
    .source(id_column="SourceGroupId", node_type="EntraGroup")
    .target(id_column="TargetGroupId", node_type="EntraGroup")
    .with_columns("SourceGroupId", "TargetGroupId", "EdgeKey",
                  key="EdgeKey", display="EdgeKey")
).done()
# Validate the schema before building.
entra_group_graph_spec.show_schema()

Buat grafik.
```
# Build = prepare data + publish for the session.
entra_group_graph = Graph.build(entra_group_graph_spec)
print(entra_group_graph.build_status.status)   # "published" or "prepared"
```
Note

Graph.build() menyiapkan data dan memublikasikannya dengan satu panggilan. Untuk memeriksa simpul dan tepi yang disiapkan sebelum menerbitkan, panggil Graph.prepare(spec), tinjau graph.nodes dan graph.edges, lalu panggil graph.publish().

Jalankan kueri GQL.

# Find nested group relationships up to 8 levels deep. 
# Update the Entra Group name that you want to traverse from 

query_nested_groups = """ 
MATCH p=(g1:EntraGroup)-[cg]->{1,8}(g2) 
WHERE g1.displayName = 'tmplevel3' 
RETURN * 
""" 
entra_group_graph.query(query_nested_groups).show()

Menguji buku catatan grafik

Uji notebook untuk memastikannya menghasilkan output grafik yang diharapkan:

Mulai ulang kernel dan jalankan semua sel di atas ke bawah.
Konfirmasikan bahwa setiap sel berhasil diselesaikan.
Jika sel transformasi berjalan lebih dari 5 menit pada kumpulan kecil, kencangkan filter rekam jepret dan proyeksi kolom sebelum meningkatkan skala.
Konfirmasikan show_schema() mengembalikan simpul dan tepi yang diharapkan.
Jalankan sampel kueri GQL dan verifikasi visualisasi dan output tabular.
Memvalidasi kasus tepi:
- Masukan kosong.
- Penyimpangan skema.
- Akses ke tabel tidak tersedia.

Tip

Tambahkan sel markdown di atas setiap bagian kode ke tujuan dokumen, input, output, dan simpul atau tepi yang dihasilkan.

Jadwalkan tugas graf untuk mematerialisasikan graf

Grafik yang dibuat dalam sesi interaktif bersifat ephemeral. Jadwalkan pekerjaan grafik untuk mempertahankan dan menyegarkan grafik. Untuk informasi selengkapnya, lihat Menjadwalkan dan mengelola pekerjaan grafik Microsoft Sentinel.

Di buku catatan grafik Anda, pilih Buat Pekerjaan Terjadwal>Buat pekerjaan grafik.
Masukkan Nama dan Deskripsi graf, lalu verifikasi jalur notebook.
Pilih jadwal:
- Sesuai permintaan: dibangun sekali, dengan retensi default 30 hari.
- Terjadwal: pilih ulangi irama dan waktu mulai/selesai.
Pilih Kirim.
Buka grafik di ekstensi Sentinel dan pantau Detail Pekerjaan.
Gunakan Jalankan Sekarang untuk menjalankan jadwal luar sesuai kebutuhan.
Konfirmasi perkembangan status dari Queued ke In Progress ke Ready.

Penting

Pekerjaan yang dikirim dipisahkan dari buku catatan lokal Anda. Mengedit .ipynb lokal tidak memperbarui tugas terjadwal. Untuk memperbarui buku catatan pekerjaan, unduh dari panel Grafik, edit, lalu gunakan Edit pekerjaan>Kirim.

Mengkueri dan memvisualisasikan dari penjelajah Graph

Setelah status pekerjaan grafik menjadi Ready, lakukan kueri dan visualisasikan di portal Defender, notebook, dan API REST.

Di portal Defender di bawah Microsoft Sentinel, buka pengalaman grafik dan pilih grafik materialisasi Anda.
Jalankan kueri GQL, periksa skema, beralih antara tampilan visual dan tabular, dan telusuri hop berikutnya.
Gunakan referensi cepat GQL ini:

Pola atau klausa	Example
Node dengan label	`(g:EntraGroup)`
Tepi yang ditik, diarahkan	`-[c:ContainsUser]->`
Jalur panjang variabel (1 hingga 8 hop)	`(a)-[e]->{1,8}(b)`
Filter	`WHERE g.displayName = 'Finance Admins'`
Pilih, urutkan, batasi	`RETURN g.displayName ORDER BY g.displayName LIMIT 10`
Ekspresi label	`(:EntraUser \\| EntraServicePrincipal)`

Note

Setiap kueri GQL dimulai dengan MATCH. Mesin beroperasi di UTC. Gunakan ZONED_DATETIME(...) untuk literal tanggal dan waktu. INSERT dan CREATE tidak didukung. Grafik bersifat baca-saja.

Kueri dari buku catatan.

from sentinel_graph import Graph
# Attach to an already-materialized graph by name.
graph = Graph.get("entra_group_membership")
graph.query("MATCH (g:EntraGroup)-[c:ContainsUser]->(u:EntraUser) RETURN g, c, u").show()
# Purpose-built security algorithms are available too:
graph.blast_radius(source_property_value="Finance Admins", min_hop_count=1).show()

Kueri dengan menggunakan Graph REST API.

GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom
Authorization: Bearer <access_token>

POST https://api.securityplatform.microsoft.com/graphs/graph-instances/{graphName}/query
Authorization: Bearer <access_token>
Content-Type: application/json
{
  "query": "MATCH (g:EntraGroup)-[c:ContainsUser]->(u) RETURN g, c, u LIMIT 100",
  "responseFormats": ["Table", "Graph"],
  "queryLanguage": "GQL"
}

responseFormats mengontrol bentuk output. "Table" mengembalikan baris, "Graph" mengembalikan simpul dan tepi, dan ["Table", "Graph"] mengembalikan keduanya.

Untuk informasi selengkapnya, lihat Graph REST API untuk grafik kustom.

Mengemas dan menerbitkan solusi grafik Anda

Setelah grafik Anda diuji dan diwujudkan, paketkan untuk penyebaran kepada pelanggan. Untuk instruksi pengemasan terperinci, lihat Mengemas dan menerbitkan solusi grafik dan buku catatan Microsoft Sentinel.

Troubleshooting

Gunakan tabel berikut untuk mendiagnosis masalah umum dengan gejala.

Penulisan grafik

Gejala	Kemungkinan penyebab dan perbaikan
`MicrosoftSentinelProvider` atau `sentinel_graph` tidak ditemukan	Masuk lagi ke ekstensi dan konfirmasikan kernel Microsoft Sentinel dipilih.
Sel macet pada "Memulai sesi Spark"	Startup pertama dapat memakan waktu 3 hingga 5 menit. Jika melebihi 6 menit, periksa kapasitas kumpulan dan coba lagi.
`show_schema()` kosong atau `Graph.build()` gagal	Pastikan kolom kunci dan kolom tampilan ada dan tidak bernilai null, serta nilai `node_type` sumber dan target sesuai dengan alias node.
Kueri GQL tidak mengembalikan baris	Konfirmasikan nilai filter ada di rekam jepret yang dipilih dan verifikasi pemfilteran rekam jepret.
`publish()` gagal karena izin ditolak	Konfirmasikan bahwa Anda memiliki peran Operator Keamanan, Administrator Keamanan, atau Administrator Global.

Penulisan yang dibantu AI

Gejala	Kemungkinan penyebab dan perbaikan
`@sentinel /graph-authoring` tidak melakukan apa-apa	Konfirmasikan ekstensi GitHub Copilot dan Jupyter diinstal dan aktif, dan Anda memiliki paket Bisnis atau Perusahaan Copilot.
Kode yang dihasilkan mereferensikan tabel yang hilang	Pastikan penyiapan konektor sudah benar dan verifikasi bahwa tabel muncul di Data Lake Explorer.

Penjadwalan pekerjaan

Gejala	Kemungkinan penyebab dan perbaikan
Pengeditan buku catatan lokal tidak tercermin dalam pekerjaan	Unduh buku catatan pekerjaan dari panel Grafik, edit, lalu gunakan Edit pekerjaan>Kirim.
Graf termaterialisasi menghilang	Grafik sesuai permintaan memiliki retensi 30 hari. Jadwalkan tugas berulang atau jalankan build baru.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-07-21

Mengembangkan solusi platform grafik kustom

Prasyarat

Permissions

Tools

Alur kerja build

Memasukkan data sampel

Memvalidasi konektivitas dengan notebook sederhana

Buat grafik kustom

Penulisan grafik yang dibantu AI

Tulis secara manual

Menguji buku catatan grafik

Jadwalkan tugas graf untuk mematerialisasikan graf

Mengkueri dan memvisualisasikan dari penjelajah Graph

Mengemas dan menerbitkan solusi grafik Anda

Troubleshooting

Penulisan grafik

Penulisan yang dibantu AI

Penjadwalan pekerjaan

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: