GQL Sorgu API'si başvurusu

Uyarı

Bu özellik şu anda genel önizlemededir. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

RESTful HTTP API'sini kullanarak Microsoft Fabric'te grafikteki özellik graflarında GQL sorguları çalıştırın. Bu başvuru http sözleşmesini açıklar: istek ve yanıt biçimleri, kimlik doğrulaması, JSON sonuç kodlaması ve hata işleme.

Önemli

Bu makale yalnızca sosyal ağ örnek grafik veri setini kullanmaktadır.

Genel Bakış

GQL Sorgu API'si, GQL sorgularını JSON yükleri olarak kabul eden ve yapılandırılmış, yazılan sonuçlar döndüren tek bir uç noktadır (HTTP üzerinden RPC). API durum bilgisi yoktur, kimlik doğrulamasını işler ve kapsamlı hata raporlama sağlar.

Temel özellikler

Tek uç nokta - Tüm işlemler bir URL'ye HTTP POST kullanır.
JSON tabanlı - İstek ve yanıt yükleri, yazılan GQL değerlerinin zengin kodlamasıyla JSON kullanır.
Durum Bilgisi Olmayan - İstekler arasında oturum durumu gerekmez.
Tür güvenli - Değer gösterimi için ayrımcı birleşimlerle güçlü, GQL uyumlu yazma.

Önkoşullar

Düğümler ve kenarlar (ilişkiler) dahil olmak üzere verileri içeren bir graf gerekir. Örnek graf oluşturmak ve yüklemek için graf hızlı başlangıcına bakın.
Yürütme sonuçlarının ve sonuçlarının yapısı da dahil olmak üzere özellik graflarını ve GQL'yi temel olarak anlamanız gerekir.
Kuruluşunuzda oturum açmak için Azure CLI aracını az yüklemeniz ve ayarlamanız gerekir. Bu makaledeki komut satırı örneklerinde bash gibi POSIX uyumlu bir komut satırı kabuğu kullanıldığı varsayılır.

Authentication

GQL Sorgu API'sinde taşıyıcı belirteçler aracılığıyla kimlik doğrulaması gerekir.

Erişim belirtecinizi her isteğin Yetkilendirme üst bilgisine ekleyin:

Authorization: Bearer <your-access-token>

Genel olarak, Microsoft Authentication Library (MSAL) veya Microsoft Entra ile uyumlu diğer kimlik doğrulama akışlarını kullanarak taşıyıcı belirteçleri alabilirsiniz.

Taşıyıcı belirteçleri genellikle iki ana yol aracılığıyla elde edilir:

Kullanıcı tarafından atanan erişim

Azure CLI aracı az aracılığıyla komut satırından kullanıcı tarafından temsilci olarak atanan hizmet çağrıları için taşıyıcı belirteçleri alabilirsiniz.

Komut satırından kullanıcı tarafından atanan çağrılar için taşıyıcı belirteci almak için:

az login komutunu çalıştırın
Sonra az account get-access-token --resource https://api.fabric.microsoft.com

Bu, Azure CLI aracını az kullanır.

İstekleri gerçekleştirmek için kullandığınızda az rest taşıyıcı belirteçleri otomatik olarak alınır.

Uygulama erişimi

Microsoft Entra kayıtlı uygulamalar için taşıyıcı belirteçleri alabilirsiniz. Diğer ayrıntılar için Doku API'sine bakın.

API uç noktası

API, tüm sorgu işlemlerini kabul eden tek bir uç nokta kullanır:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true

çalışma alanınızın öğesini {workspaceId} almak için, kullanarak az resttüm kullanılabilir çalışma alanlarını listeleyebilirsiniz:

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces"

elde {graphId}etmek için kullanarak bir çalışma alanında az restbulunan tüm kullanılabilir grafikleri listeleyebilirsiniz:

az rest --method get --resource "https://api.fabric.microsoft.com" --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels"

Sorgu sonuçlarını daha da daraltmak için daha fazla parametre kullanabilirsiniz:

--query 'value[?displayName=='My Workspace'] yalnızca öğesi displayName olan öğeleri listelemek My Workspaceiçin.
--query 'value[starts_with(?displayName='My')]yalnızca ile displayNamebaşlayan öğeleri My listelemek için.
--query '{query}' yalnızca sağlanan JMESPath {query}ile eşleşen öğeleri listelemek için. için desteklenen söz dizimine ilişkin JMESPath Azure CLI belgelerine bakın.
-o table tablo sonucu üretmek için.

Uyarı

Komut satırı kabuğundan API uç noktası üzerinden sorgu yürütme hakkında az-rest kullanma bölümüne veya curl kullanma bölümüne bakın.

İstek başlıkları

Header	Değer	Gerekli
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer <token>`	Yes

İstek biçimi

Tüm istekler JSON yükü ile HTTP POST kullanır.

Temel istek yapısı

{
  "query": "MATCH (n) RETURN n LIMIT 100"
}

İstek alanları

Veri Alanı	Türü	Gerekli	Description
`query`	String	Yes	Yürütülecek GQL sorgusu

Yanıt biçimi

Başarılı istekler için tüm yanıtlar, yürütme durumu ve sonuçları içeren JSON yükü ile HTTP 200 durumunu kullanır.

Yanıt yapısı

{
  "status": {
    "code": "00000",
    "description": "note: successful completion", 
    "diagnostics": {
      "OPERATION": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Durum nesnesi

Her yanıt, yürütme bilgilerini içeren bir durum nesnesi içerir:

Veri Alanı	Türü	Description
`code`	String	altı karakterli durum kodu (000000 = başarı)
`description`	String	İnsan tarafından okunabilir durum iletisi
`diagnostics`	object	Ayrıntılı tanılama kayıtları
`cause`	object	İsteğe bağlı temel neden durum nesnesi

Durum kodları

Durum kodları hiyerarşik bir desene uyar:

00xxxx - Tam başarı
01xxxx - Uyarılarla başarı
02xxxx - Veri olmadan başarı
03xxxx - Bilgiyle başarı
04xxxx ve üzeri - Hatalar ve özel durum koşulları

Daha fazla bilgi için bkz. GQL durum kodları başvurusu.

Tanılama kayıtları

Tanılama kayıtları, durum nesnesini daha ayrıntılı olarak ayrıntılandıran diğer anahtar-değer çiftlerini içerebilir. Alt çizgiyle (_) başlayan tuşlar grafiğe özeldir. GQL standardı diğer tüm anahtarları reçete eder.

Uyarı

Grafiğe özgü anahtarların tanılama kaydındaki değerler JSON ile kodlanmış GQL değerleridir. Bkz . Değer türleri ve kodlama.

Nedenler

Durum nesneleri, temel bir neden bilindiğinde isteğe bağlı cause bir alan içerir.

Diğer durum nesneleri

Bazı sonuçlar diğer durum nesnelerini (isteğe bağlı) additionalStatuses alanında liste olarak bildirebilir.

Öyleyse, birincil durum nesnesi her zaman GQL standardı tarafından belirlenen en kritik durum nesnesi (özel durum koşulu gibi) olarak belirlenir.

Sonuç türleri

Sonuçlar, alanıyla ayrımcı bir birleşim deseni kind kullanır:

Tablo sonuçları

Tablo verileri döndüren sorgular için:

{
  "kind": "TABLE",
  "columns": [
    {
      "name": "name",
      "gqlType": "STRING",
      "jsonType": "string"
    },
    {
      "name": "age",
      "gqlType": "INT32",
      "jsonType": "number"
    }
  ],
  "isOrdered": true,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Atlanmış sonuçlar

Veri döndürmeyen işlemler için (örneğin, katalog ve/veya veri güncelleştirmeleri):

{
  "kind": "NOTHING"
}

Değer türleri ve kodlama

API, GQL değerlerini hassas semantiklerle temsil etmek için zengin bir tür sistemi kullanır. GQL değerlerinin JSON biçimi, ayrımcı birleşim desenini izler.

Uyarı

Tablosal sonuçların JSON biçimi, ayırarak gqlType ve value daha kompakt bir gösterim elde ederek ayrımcı birleşim desenini uygular. Bkz. Tablo serileştirme iyileştirmesi.

Değer yapısı

{
  "gqlType": "TYPE_NAME",
  "value": <type-specific-value>
}

İlkel türler

GQL Türü	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Yerel JSON boole değeri
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8 dizesi

Sayısal türler

Tamsayı türleri

GQL Türü	Aralık	JSON Serileştirme	Example
`INT64`	-2⁶³'den 2⁶³-1'e	Sayı veya dize*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 - 2⁶⁴-1	Sayı veya dize*	`{"gqlType": "UINT64", "value": 18467}`

JavaScript'in güvenli aralığı dışındaki büyük tamsayılar (-9.007.199.254.740.991 ile 9.007.199.254.740.991) dize olarak serileştirilir:

{"gqlType": "INT64", "value": "9223372036854775807"}
{"gqlType": "UINT64", "value": "18446744073709551615"}

Kayan nokta türleri

GQL Türü	Aralık	JSON Serileştirme	Example
`FLOAT64`	IEEE 754 binary64	JSON numarası veya dizesi	`{"gqlType": "FLOAT64", "value": 3.14}`

Kayan nokta değerleri IEEE 754 özel değerlerini destekler:

{"gqlType": "FLOAT64", "value": "Inf"}
{"gqlType": "FLOAT64", "value": "-Inf"}
{"gqlType": "FLOAT64", "value": "NaN"}
{"gqlType": "FLOAT64", "value": "-0"}

Zamana bağlı türler

Desteklenen zamansal türler ISO 8601 dize biçimlerini kullanır:

GQL Türü	Biçim	Example
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Graph öğesi başvuru türleri

GQL Türü	Description	Example
`NODE`	Grafik düğümü başvurusu	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Graf kenar başvurusu	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Karmaşık türler

Karmaşık türler diğer GQL değerlerinden oluşur.

Lists

Listeler, tutarlı öğe türlerine sahip null atanabilir değer dizileri içerir:

{
  "gqlType": "LIST<INT64>",
  "value": [1, 2, null, 4, 5]
}

Özel liste türleri:

LIST<ANY> - Karışık türler (her öğe tam tür bilgileri içerir)
LIST<NULL> - Yalnızca null değerlere izin verilir
LIST<NOTHING> - Her zaman boş dizi

Paths

Yollar, grafik öğesi başvuru değerlerinin listesi olarak kodlanır.

{
    "gqlType": "PATH",
    "value": ["node1", "edge1", "node2"]
}

Bkz. Tablo serileştirme iyileştirmesi.

Tablo serileştirme iyileştirmesi

Tablo sonuçları için değer serileştirme, sütun türü bilgilerine göre iyileştirilmiştir:

Bilinen türler - Yalnızca ham değer serileştirilir
ANY sütunları - Tür ayrıştırıcısı ile tam değer nesnesi

{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Hata yönetimi

Aktarım hataları

Ağ ve HTTP aktarım hataları standart HTTP hata durum kodlarıyla (4xx, 5xx) sonuçlanır.

Uygulama hataları

Uygulama düzeyi hataları her zaman durum nesnesinde hata bilgileriyle HTTP 200 döndürür:

{
  "status": {
    "code": "42001",
    "description": "error: syntax error or access rule violation",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_errorLocation": {
        "gqlType": "STRING",
        "value": "line 1, column 15"
      }
    },
    "cause": {
      "code": "22007",
      "description": "error: data exception - invalid date, time, or, datetime
format",
      "diagnostics": {
        "OPERATION": "query",
        "OPERATION_CODE": "0",
        "CURRENT_SCHEMA": "/"
      }
    }
  }
}

Durum denetimi

Başarıyı belirlemek için durum kodunu denetleyin:

, , 000102 ile 03başlayan kodlar başarıyı gösterir (olası uyarılarla)
Diğer tüm kodlar hataları gösteriyor

az rest ile tam örnek

Taşıyıcı belirteçleri el ile almak zorunda kalmamak için komutunu kullanarak az rest bir sorgu çalıştırın, örneğin:

az rest --method post --url "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
--headers "Content-Type=application/json" "Accept=application/json" \
--resource "https://api.fabric.microsoft.com" \
--body '{ 
  "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
}'

Curl ile tam örnek

Bu bölümdeki örnek, kabuktan HTTPS istekleri gerçekleştirmek için aracı kullanır curl .

Kabuk değişkeninde depolanan geçerli bir erişim belirtecinin olduğunu varsayarız, örneğin:

export ACCESS_TOKEN="your-access-token-here"

Tavsiye

Geçerli bir taşıyıcı belirteci edinme hakkında kimlik doğrulaması bölümüne bakın.

Şu şekilde bir sorgu çalıştırın:

curl -X POST "https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/GraphModels/{GraphModelId}/executeQuery?preview=true" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "MATCH (n:Person) WHERE n.birthday > 19800101 RETURN n.firstName, n.lastName, n.birthday ORDER BY n.birthday LIMIT 100" 
  }'

En iyi yöntemler

GQL Sorgu API'sini kullanırken bu en iyi yöntemleri izleyin.

Hata yönetimi

Durum kodlarını her zaman denetle - HTTP 200'e göre başarılı olduğunu varsaymayın.
Hata ayrıntılarını ayrıştırma - Tanılamayı kullanın ve hata ayıklama için zincirlere neden olun.

Security

HTTPS kullanma - Hiçbir zaman şifrelenmemiş bağlantılar üzerinden kimlik doğrulama belirteçleri göndermeyin.
Belirteçleri döndürme - Doğru belirteç yenileme ve süre sonu işlemeyi uygulayın.
Girişleri doğrulama - Sorguya eklenen kullanıcı tarafından sağlanan sorgu parametrelerini temizleyip düzgün bir şekilde kaçış yapın.

Değer gösterimi

Büyük tamsayı değerlerini işleme - Tamsayılar yerel olarak JSON numaraları olarak gösterilemiyorsa dize olarak kodlanır.
Özel kayan nokta değerlerini işleme - Sorgulardan döndürülen kayan nokta değerleri , Infinityveya -Infinity (sayı değil) değerleri olabilirNaN.
Null değerleri işleme - JSON null değeri GQL null değerini temsil eder.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-03-12

GQL Sorgu API'si başvurusu

Genel Bakış

Temel özellikler

Önkoşullar

Authentication

Kullanıcı tarafından atanan erişim

Uygulama erişimi

API uç noktası

İstek başlıkları

İstek biçimi

Temel istek yapısı

İstek alanları

Yanıt biçimi

Yanıt yapısı

Durum nesnesi

Durum kodları

Tanılama kayıtları

Nedenler

Diğer durum nesneleri

Sonuç türleri

Tablo sonuçları

Atlanmış sonuçlar

Değer türleri ve kodlama

Değer yapısı

İlkel türler

Sayısal türler

Tamsayı türleri

Kayan nokta türleri

Zamana bağlı türler

Graph öğesi başvuru türleri

Karmaşık türler

Lists

Paths

Tablo serileştirme iyileştirmesi

Hata yönetimi

Aktarım hataları

Uygulama hataları

Durum denetimi

az rest ile tam örnek

Curl ile tam örnek

En iyi yöntemler

Hata yönetimi

Security

Değer gösterimi

İlgili içerik

Geri Bildirim

Ek kaynaklar