GQL Sorgu API'si başvurusu

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, GQL sorgularını JSON yükü olarak kabul eden ve yapılandırılmış, tiplenmiş sonuçlar döndüren bir REST uç noktası sunar. İlk istek sırasında bitmeyen sorgular için devam anketini destekliyor.

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.
Devamlı anket - Uzun süreli sorgular, birden fazla HTTP isteği arasında devam edebilir.
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?beta=true

Query API beta aşamasında ve üretim kullanımı için önerilmez. Gerekli beta sorgu parametresini ayarlayın true. Eski preview=true parametre geriye dönük uyumluluk için desteklenmeye devam ediyor, ancak yeni entegrasyonlar için kullanılıyor beta=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 {graphModelId}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"

Bu liste isteklerinden gelen yanıtları filtrelemek veya biçimlendirmek için Azure CLI çıktı seçeneklerini kullanabilirsiniz. Bu seçenekler Azure CLI istemcisinde çalışır; bunlar Query API parametreleri değildir:

--query "value[?displayName=='My Workspace']" Sadece 'den bir displayNameMy Workspaceöğe listeler.
--query "value[?starts_with(displayName, 'My')]"Sadece ile Mybaşlayan öğeleri displayName listeler.
--query "{query}" Yalnızca sağlanan JMESPath {query}ile eşleşen öğeleri listeler. Desteklenen sözdizimi için Query Azure CLI komut sonuçlarına bakınız.
-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.

Sorgu parametreleri

Parametre	Türü	Gerekli	Description
`beta`	boole	Yes	Beta Sorgu API'sini kullanmak için ayarlandı `true` .
`continuationToken`	String	Hayır	Bir sorgu hâlâ çalışırken kullanılan token `result.nextPage` . Tokenı kullanırken aynı sorgu metnini gönderin.

İ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": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "00000"
      }
    }
  },
  "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	Beş karakterli halka açık API durum kodu.
`description`	String	İnsan tarafından okunabilir durum tanımı.
`diagnostics`	object	Mevcut olduğunda kanonik sorgu motoru GQLSTATUS dahil olmak üzere ayrıntılı tanı kaydı.
`cause`	object	İstereğe bağlı temel neden durumu nesnesi.

Durum kodları

Birincil status.code bu genel API kategorilerini kullanır:

00000 - En az bir sıra ile başarılı tamamlama.
00001 - Başarısız bir sonuç ile başarılı tamamlama. Gelecekteki DDL ve DML desteği için ayrılmıştır.
01000 - Uyarı veya bilgilendirici durum.
02000 - Şu anda satır üreten sorgudan satır mevcut değildir.
42000 - Sözdizim, erişim kuralı veya kullanıcı tarafından düzeltilebilen başka bir sorgu hatası.
50000 - Sistem veya sınıflandırılmamış hata.

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ı

Tanılama, _graphaneGqlStatus sorgu motoru tarafından bildirilen kanonik beş karakterli GQLSTATUS'u içerir. Her alt çizgi ön ekli tanı üyesi, JSON kodlu GQL değerinden birini null veya bir JSON ile kodlanmış bir değeri içerir. Örneğin, _graphaneGqlStatusSTRING, kullanırken, hata sınıflandırma tanıları BOOL. 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, isteğe additionalStatuses bağlı alanda diğer durum nesnelerini liste olarak bildirebilir.

Birincil durum, en kritik kaydedilen durumdur. Her ek durum ve iç içe neden kendi açık API kodu ve kanonik GQLSTATUS tanılaması vardır.

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": "INT64",
      "jsonType": "number|string"
    }
  ],
  "isOrdered": false,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Uzun süre çalışan sorgular

Bir sorgu mevcut HTTP isteği sırasında bitmezse, API HTTP 200'ü halka açık durum kodu 02000, boş bir tablo ve bir nextPage token ile döndürür:

{
  "status": {
    "code": "02000",
    "description": "No data available, retry with continuation token"
  },
  "result": {
    "kind": "TABLE",
    "columns": [],
    "data": [],
    "nextPage": "{continuationToken}"
  }
}

Aynı istek gövdesini gönderip tokenı URL'ye ekleyerek tamamlamak için anket yapın:

POST https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/graphModels/{graphModelId}/executeQuery?beta=true&continuationToken={continuationToken}

Opak bir değer olarak ele nextPage alın. RFC 3986'ya göre tam bir kez yüzde kodlayın, sonra sorgu-parametre değeri olarak kullanın continuationToken . Tokenı çözmeyin, incelemeyin veya değiştirmeyin.

Yanıt artık içermeyene nextPagekadar devam edin. Sorgu yürütme, ilk istekten itibaren 20 dakikaya kadar devam edebilir. Eğer bu toplam süreyi aşarsa, API hata kodu QueryTimeoutile HTTP 408 döndürür.

Kısaltılmış sonuçlar

Graph, iç ikili temsili 64 MB'yi aştığında sorgu yanıtını kestirir. API, uyan satırları döndürür ve 'ye additionalStatusesbir durum ekler. Ek durum, kamu kodu 01000 kullanır ve kanonik GQLSTATUS'u 01M11 korur._graphaneGqlStatus

Kesinti, çıkarılan satırlar için bir nextPage token üretmez. Sorguyu filtreler, belirli projeksiyonlar veya LIMITile daraltın ve sonra tekrar çalıştırın.

Atlanmış sonuçlar

Yanıt şeması, veri veya değerlendirme sonucundan bağımsız olarak ifadesi satır üretmeyen bir işlemi temsil edebilir. Bu sonuç durum kodu 00001kullanır:

{
  "kind": "NOTHING"
}

Bu çıkarılan sonuç, satır olmayan bir tablodan farklıdır. Boş tablo, şu anda döndürülecek satır olmayan bir satır üreten sorguyu değerlendirmenin sonucudur.

Graph, bu sonuç şekli ve durum kodunu gelecekteki veri tanım dili (DDL) ve veri işleme dili (DML) bildirimi desteği için saklar. Güncel sorgu ifadeleri her zaman tablo sonuçlarını döndürür.

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

{
  "kind": "TABLE",
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "amount", "gqlType": "INT64", "jsonType": "number|string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "object"}
  ],
  "data": [
    {
      "name": "Alice",
      "amount": "123",
      "mixed": {"gqlType": "INT64", "value": "1"}
    }
  ]
}

Hata yönetimi

Aktarım hataları

HTTP durumu ve GQL durumu, yanıtın farklı katmanlarını tanımlar:

HTTP durumu	Meaning
200	API isteği işledi. İncele `status.code` yapın çünkü sonuç başarıyı, satır yokluğunu, hala devam eden bir sorgu veya kullanıcı tarafından düzeltilebilen bir sorgu hatasını temsil edebilir.
408	Sorgu yürütme süresi toplam 20 dakikalık molayı aştı. Hata kodu şeklindedir `QueryTimeout`.
429	Hizmet fiyatı sınırı aşıldı. Tekrar denemeden önce başlıktaki süreyi `Retry-After` bekleyin.
499	Arayan kişi talebi iptal etti. Hata kodu şeklindedir `ClientCancelled`.
Diğer 4xx veya 5xx	İstek veya hizmet, GQL yürütme sonucunu döndürmeden önce başarısız oldu. HTTP hata yanıtını inceleyin.

Uygulama hataları

Uygulama düzeyinde bir hata, durum nesnesinde hata bilgisi olan HTTP 200 döndürebilir. Örneğin, sıfıra bölme, genel API kodunu 42000 kullanır ve tanı kaydında kanonik GQLSTATUS'u 22012 korur:

{
  "status": {
    "code": "42000",
    "description": "error: data exception - division by zero",
    "diagnostics": {
      "OPERATION": "query",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/",
      "_graphaneGqlStatus": {
        "gqlType": "STRING",
        "value": "22012"
      },
      "_graphaneIsUserError": {
        "gqlType": "BOOL",
        "value": true
      },
      "_graphaneIsTransientError": {
        "gqlType": "BOOL",
        "value": false
      }
    }
  }
}

Durum denetimi

Genel sonucu belirlemek için halkı status.codekontrol edin. Uygulamanızda belirli bir sorgu-motoru koşunu, örneğin sayısal taşma (22003) ile sıfıra bölme (22012) ayırt etmek gerekirse kullanın_graphaneGqlStatus.

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?beta=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?beta=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.
Girdileri doğrulama - Uygulamanızın sorgu metnine eklediği kullanıcı tarafından sağlanan değerleri doğrulayarak doğru şekilde kaçını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şle - API, pozitif sonsuzluk, negatif sonsuzluk, sayı olmayan ve negatif sıfırı , "-Inf", "NaN", ve "-0"olarak "Inf"serileştirir.
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-09-29

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ı

Sorgu parametreleri

İ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ı

Uzun süre çalışan sorgular

Kısaltılmış 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