Özel graf platformu çözümleri geliştirme

Note

Bu özellik şu anda önizlemededir. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları'na bakın.

Microsoft Sentinel özel graf çözümü, Microsoft Sentinel data lake tablolarından düğümleri ve kenarları tanımlayan, graf oluşturan ve kullanıcıların grafı Graph Sorgu Dili (GQL) ile sorgulamasına olanak tanıyan not defteri tabanlı bir çözümdür.

Müşterilerin Microsoft Güvenlik Store'da bulabilmesi için özel graf çözümünü Microsoft İş Ortağı Merkezi'de SaaS teklifi olarak oluşturmak, test etmek, uygulamak, paketlemek ve yayımlamak için bu kılavuzu kullanın.

Prerequisites

Özel Graf çözümleri oluşturmak için veri gölüne eklenmelisiniz. Daha fazla bilgi için Microsoft Sentinel veri gölüne nasıl katılacağınızı öğrenin.

Permissions

Aşağıdaki tabloda, bu kılavuzdaki her işlem veya kapsam için gerekli izinler listelanmaktadır.

Operation	Gerekli rol
Sentinel veri gölüne dahil olma	Microsoft Entra ID - Güvenlik Yöneticisi veya Genel Yönetici
Sentinel çalışma alanını Defender portala ekleme	Abonelik Sahibi veya abonelik kapsamında Kullanıcı Erişimi Yöneticisi ve abonelik ya da kaynak grubu kapsamında Microsoft Sentinel Katkıda Bulunanı
Sentinel çalışma alanını veri gölüne ekleyin	Abonelik veya kaynak grubu kapsamında Abonelik Sahibi veya Microsoft Sentinel Katkıda Bulunanı
Not defteri grafiği modelleme ve oluşturma	Microsoft Sentinel veri toplama için `data (manage)` iznine sahip özel Microsoft Defender XDR birleşik RBAC rolü
Bir grafı kalıcı olarak kaydetme (somutlaştırma)	Güvenlik İşleci, Güvenlik Yöneticisi veya Genel Yönetici
Kalıcı grafiği sorgulama	Microsoft Sentinel veri toplaması üzerinde `security data basics (read)` ile özel Microsoft Defender XDR birleşik RBAC rolü
Özel Graf çözümü yayımlama	Microsoft İş Ortağı Merkezi'da Market Publisher hesabı

Araçlar

Özel graf çözümü oluşturmak ve yayımlamak için aşağıdaki araçlar gereklidir:

Visual Studio Code.
Visual Studio Code için Microsoft Sentinel uzantısı. Daha fazla bilgi için Install Visual Studio Code ve Microsoft Sentinel uzantısına bakınız.
Visual Studio Code için Jupyter uzantısı.
GitHub Copilot uzantısı ve GitHub Copilot İş veya Kurumsal planı.
Yerel makinenizde Python 3.10 veya sonraki bir sürüm.

Tip

Kiracınız KQL sorguları, not defterleri veya bir Güvenlik Copilot aracısı için zaten kullanıma alınmışsa mevcut bir veri gölünü yeniden kullanın. Kiracı başına bir veri gölü vardır. Defender portalında Sistem>Ayarları>Microsoft Sentinel>Veri gölü'ne gidin. Durum Sağlandı ise 1. görevi atlayın.

İş akışı oluşturma

Aşağıdaki iş akışında özel graf çözümü oluşturma ve yayımlama adımları özetlenmiştir.

Örnek verileri grafınızın modellerini oluşturan tablolara alın.
Basit bir not defteriyle bağlantıyı doğrulayın.
Özel grafı yazın.
Grafik not defterini test edin.
Grafı somutlaştırmak için bir graf görevi zamanlayın.
Graf gezgininden grafiği sorgulayıp görselleştirin.
Özel graf çözümünü paketleyin ve yayımlayın.

Örnek verileri ekleme

Bu görev, bu kılavuzdaki örnek grafikte kullanılan Microsoft Entra ID varlık tablolarını içeri aktarır: EntraUsers, EntraGroups, EntraServicePrincipals ve EntraMembers.

Defender portalında Sistem>Ayarları>Microsoft Sentinel>Veri bağlayıcıları'na gidin.
Entra varlık tablolarının veri gölüne alınabilmesi için Microsoft Entra ID bağlayıcısını etkinleştirin. Daha fazla bilgi için, Microsoft Sentinel veri gölünde Varlık verileri'ne bakınız.
Bu tabloların Data Lake Explorer'da göründüğünü onaylayın:
- EntraUsers
- EntraGroups
- EntraServicePrincipals
- EntraMembers
Bu tablolar Sistem tabloları çalışma alanına iner.
İsteğe bağlı: Senaryonuz farklı veriler kullanıyorsa, sonraki adımlarda diğer bağlayıcıları alın ve tablo adlarını değiştirin.

Note

Data Lake Explorer'da bir tablo görünmüyorsa, bunu grafik yazma için kullanamazsınız ve yapay zeka yardımı buna başvurmaz.

Basit bir not defteriyle bağlantıyı doğrulama

Graf yazmadan önce data lake bağlantısını doğrulamak için en düşük not defterini oluşturun ve çalıştırın.

Visual Studio Code açın ve data lake'e erişimi olan hesapla Microsoft Sentinel uzantısında oturum açın.
Visual Studio Code'da Sentinel Uzantısı-Grafikler altında Yeni not defteri oluştur'u seçin.
Not defterini kaydedin, örneğin hello-world-show-tables.ipynb.
Çekirdek seç seçin, Microsoft Sentinel'i seçin ve kullanılabilir bir Spark havuzu seçin.
Aşağıdaki hücreleri sırayla ekleyin.

Hücre 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

Hücre 2 - Kod (çalışma alanınızı bağlayın ve ayarlayın):

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}")

Hücre 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.

Hücre 4 - Kod (tabloyu okuyun ve satırları gösterin):

# 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)

Hücre 5 - Kod (isteğe bağlı gizlilik sayıları):

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

Tüm hücreleri yukarıdan aşağıya çalıştırın.
Her hücrenin kırmızı bir hata çıktısı olmadan tamamlandığını, tablo önizleme verilerinin görüntülendiğini ve satır sayısının sıfır olmadığını doğrulayın.

Note

Okumalar başarısız olursa veya hiç satır döndürmezse, Örnek verileri içe aktar bölümündeki bağlayıcının ilk anlık görüntü alma işlemini tamamladığını, LOG_ANALYTICS_WORKSPACE gerçek bir çalışma alanıyla eşleştiğini ve hesabınızın okuma erişimine sahip olduğunu doğrulayın. Verilerin mevcut olduğunu onaylamak için Defender portalında KQL ile tablo içeriğini denetleyin. Daha fazla bilgi için bkz. Microsoft Sentinel veri gölünde KQL sorguları çalıştırma.

Özel grafı yazma

Şu yöntemlerden biriyle içerik oluşturun:

Yapay zeka destekli grafik yazma.
El ile yazın.

Yapay zeka destekli grafik yazma

Yapay zeka yardımıyla bir grafik yazmak için şu adımları izleyin:

Visual Studio Code'da GitHub Copilot Chat'ı açın.

İstemi graf yazma yardımcısıyla @sentinel /graph-authoring başlatın ve grafiğinizi düz dilde açıklayın:

@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 grafik yazma yaşam döngüsü için aşağıdaki hücreleri oluşturur:

Yaşam döngüsü aşaması	Oluşturulan çıktı
Ortam kurulumu	Gerekli paketleri ve bağlantı bilgilerini doğrular
Veri yükleme	Sentinel data lake'ten adlandırılmış tabloları okur
Veri dönüştürme	Düğüm ve kenar verilerini hazırlar
Grafik şeması	Düğümleri ve kenarları tanımlar
Şema doğrulaması	Graf tanımını doğrular
Grafik oluşturma	Oturum için grafı oluşturur
Graf sorgusu	Örnek bir GQL sorgusu çalıştırır ve sonucu görselleştirir

Aşağıdaki gibi istemlerle not defterini iyileştirmeye devam edin:

Goal	Prompt
İlişki ekleme	`@sentinel Add an edge from User to IPAddress`
Veriyi filtrele	`@sentinel Filter the data to show only failed sign-ins`
Zaman aralığını değiştirme	`@sentinel Change the time range to the last 7 days`
Derleme hatalarını düzeltme	`@sentinel Fix the error in the graph build step`
Kodu anlama	`@sentinel Explain how edge keys are defined`
Bir API’yi düzenlemeden bulun	`What parameters does build_graph_with_data() accept? #Sentinel`

Tip

Not defteri hücreleri oluşturmak veya değiştirmek için kullanın @sentinel /graph-authoring . API açıklamalarına ya da örnek sorgulara ihtiyacınız varsa Copilot’a sorun ve Sentinel’e özgü yanıtlar için #Sentinel ifadesini ekleyin.

Elle yazma

Grafı el ile yazmak için şu adımları izleyin:

Varlık tablolarını bağlayın ve okuyun.

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")
)

Düğüm ve uç DataFrame'leri hazırlayın.

# 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")))
)

Grafik şemasını tanımlayın ve DataFrame'leri bağlayın.

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()

Grafı oluşturun.
```
# 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() verileri hazırlar ve tek bir çağrıda yayımlar. Yayımlamadan önce hazırlanan düğümleri ve kenarları incelemek için Graph.prepare(spec) çağırın, graph.nodes ve graph.edges gözden geçirin, ardından graph.publish() çağırın.

GQL sorgusu çalıştırın.

# 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()

Graf not defterini sınayın

Beklenen graf çıkışını ürettiğinden emin olmak için not defterini test edin:

Çekirdeği yeniden başlatın ve tüm hücreleri yukarıdan aşağıya çalıştırın.
Her hücrenin başarıyla tamamlanmasını onaylayın.
Dönüştürme hücreleri küçük bir havuzda 5 dakikadan uzun sürüyorsa, ölçek büyütmeden önce anlık görüntü filtrelerini daraltın ve sütun projeksiyonunu azaltın.
show_schema() öğesinin beklenen düğümleri ve kenarları döndürdüğünü doğrulayın.
Örnek bir GQL sorgusu çalıştırın ve görselleştirmeyi ve tablosal çıkışı doğrulayın.
Uç durumlarını doğrulama:
- Boş giriş.
- Şema kayması.
- Tabloya erişim eksik.

Tip

Belge amacı, girişler, çıkışlar ve üretilen düğümler veya kenarlar için her kod bölümünün üzerine markdown hücreleri ekleyin.

Grafı somutlaştırmak için bir graf işi zamanlayın

Etkileşimli bir oturumda oluşturulan grafikler kısa ömürlü olur. Grafiği kalıcı hale getirmek ve yenilemek için bir grafik işi zamanlayın. Daha fazla bilgi için bkz. Microsoft Sentinel grafik işlerini zamanlama ve yönetme.

Graf not defterinizde, Zamanlanmış İş Oluştur>Graf işi oluştur seçin.
Grafik Adı ve Açıklama girin ve not defteri yolunu doğrulayın.
Bir zamanlama seçin:
- İsteğe bağlı: varsayılan 30 günlük saklama süresiyle bir kez derlenir.
- Zamanlandı: Yineleme temposu ve başlangıç/bitiş saatlerini seçin.
Gönderseçin.
Sentinel uzantısında grafiği açın ve İş Ayrıntıları'nı izleyin.
Gerektiğinde zamanlama dışında çalıştırmak için Şimdi Çalıştır seçeneğini kullanın.
Queued durumundan In Progress durumuna ve ardından Ready durumuna ilerleyişi onaylayın.

Important

Gönderilen işler, yerel not defterinizden bağımsızdır. Yerel .ipynb öğesini düzenlemek zamanlanmış görevi güncellemez. Bir iş not defterini güncelleştirmek için Graflar panelinden indirin, düzenleyin ve ardından İşi> düzenleGönder'i kullanın.

Graph gezgininden sorgulama ve görselleştirme

Grafik işi durumu Ready olduktan sonra Defender portalında, not defterlerinde ve REST API'lerinde sorgulayın ve görselleştirin.

Defender portalında Microsoft Sentinel altında graf deneyimini açın ve somutlaştırılmış grafınızı seçin.
GQL sorgularını çalıştırın, şemayı inceleyin, görsel ve tablo çıktılarını değiştirin ve sonraki atlamadan geçiş yapın.
Bu GQL hızlı başvuru kılavuzunu kullanın:

Desen veya yan tümcesi	Example
Etiketli düğüm	`(g:EntraGroup)`
Tipli, yönlendirilmiş kenar	`-[c:ContainsUser]->`
Değişken uzunluklu yol (1 - 8 atlama)	`(a)-[e]->{1,8}(b)`
Filter	`WHERE g.displayName = 'Finance Admins'`
Projelendir, sırala, sınırla	`RETURN g.displayName ORDER BY g.displayName LIMIT 10`
Etiket ifadeleri	`(:EntraUser \\| EntraServicePrincipal)`

Note

Her GQL sorgusu MATCH ile başlar. Motor UTC'de çalışır. Tarih-saat sabitleri için ZONED_DATETIME(...) kullanın. INSERT ve CREATE desteklenmez. Grafikler salt okunur durumdadır.

Bir not defterinden sorgu.

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()

Graph REST API'lerini kullanarak sorgulama.

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 çıkış şeklini denetler. "Table" satırları döndürür, "Graph" düğümleri ve kenarları döndürür ve ["Table", "Graph"] her ikisini de döndürür.

Daha fazla bilgi için bkz . Özel grafikler için Graf REST API'leri.

Grafik çözümünüzü paketleme ve yayımlama

Grafiğiniz test edilip somutlaştırıldıktan sonra, müşterilere dağıtmak üzere paketleyin. Ayrıntılı paketleme yönergeleri için bkz. Microsoft Sentinel grafik ve not defteri çözümlerini paketleme ve yayımlama.

Sorun giderme

Yaygın sorunları belirtiye göre tanılamak için aşağıdaki tabloları kullanın.

Graf oluşturma

Belirti	Olası neden ve düzeltme
`MicrosoftSentinelProvider` veya `sentinel_graph` bulunamadı	Uzantıda yeniden oturum açın ve Microsoft Sentinel çekirdeğinin seçili olduğunu onaylayın.
Hücre, "Starting Spark session" sırasında takılı kalıyor	İlk başlatma 3-5 dakika sürebilir. 6 dakikayı aşarsa havuz kapasitesini denetleyin ve yeniden deneyin.
`show_schema()` boş veya `Graph.build()` başarısız oluyor	Anahtar ve görüntüleme sütunlarının mevcut olduğunu ve NULL olmadığını, ayrıca kaynak ve hedefteki `node_type` değerlerinin düğüm takma adlarıyla eşleştiğini onaylayın.
GQL sorgusu hiç satır döndürmez	Seçili anlık görüntüde filtre değerlerinin mevcut olduğunu onaylayın ve anlık görüntü filtrelemeyi doğrulayın.
`publish()` izin reddedildi hatası veriyor	Güvenlik operatörü, Güvenlik Yöneticisi veya Genel Yönetici rolünüz olduğunu onaylayın.

Yapay zeka destekli yazma

Belirti	Olası neden ve düzeltme
`@sentinel /graph-authoring` hiçbir şey yapmaz	GitHub Copilot ve Jupyter uzantılarının yüklendiğini ve etkin olduğunu ve bir Copilot İş veya Kurumsal planınız olduğunu onaylayın.
Oluşturulan kod eksik bir tabloya başvurur	Bağlayıcı kurulumunu onaylayın ve tablonun Data Lake Explorer'da göründüğünü doğrulayın.

İş planlama çizelgeleme

Belirti	Olası neden ve düzeltme
Yerel not defteri düzenlemeleri işe yansıtılamıyor	graflar panelinden iş not defterini indirin, düzenleyin ve ardından İşi> düzenleGönder'i kullanın.
Somutlaştırılmış grafik kayboldu	İsteğe bağlı grafikler 30 günlük saklama süresine sahiptir. Yinelenen bir görevi zamanlayabilir veya yeni bir derleme başlatabilirsiniz.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Son güncelleştirme: 2026-07-21

Özel graf platformu çözümleri geliştirme

Prerequisites

Permissions

Araçlar

İş akışı oluşturma

Örnek verileri ekleme

Basit bir not defteriyle bağlantıyı doğrulama

Özel grafı yazma

Yapay zeka destekli grafik yazma

Elle yazma

Graf not defterini sınayın

Grafı somutlaştırmak için bir graf işi zamanlayın

Graph gezgininden sorgulama ve görselleştirme

Grafik çözümünüzü paketleme ve yayımlama

Sorun giderme

Graf oluşturma

Yapay zeka destekli yazma

İş planlama çizelgeleme

İlgili içerik

Geri Bildirim

Ek kaynaklar