Referensi API Kueri GQL

Jalankan kueri GQL terhadap grafik properti dalam grafik di Microsoft Fabric menggunakan API HTTP RESTful. Referensi ini menjelaskan kontrak HTTP: format permintaan dan respons, autentikasi, pengodean hasil JSON, dan penanganan kesalahan.

Penting

Artikel ini secara eksklusif menggunakan himpunan data grafik contoh jejaring sosial.

Gambaran Umum

API Kueri GQL menampilkan endpoint REST yang menerima kueri GQL sebagai payload JSON dan mengembalikan hasil yang terstruktur dan diketik. Aplikasi ini mendukung polling lanjutan untuk kueri yang tidak selesai selama permintaan awal.

Fitur utama

Titik akhir tunggal - Semua operasi menggunakan HTTP POST ke satu URL.
Berbasis JSON - Payload permintaan dan respons menggunakan JSON dengan pengodean kaya dari nilai GQL yang diketik.
Polling lanjutan - Kueri yang berjalan lama dapat berlanjut di beberapa permintaan HTTP.
Jenis aman - Pengetikan yang kuat dan kompatibel dengan GQL dengan penyatuan yang diskriminasi untuk representasi nilai.

Prasyarat

Anda memerlukan grafik yang berisi data, termasuk simpul dan tepi (hubungan). Lihat mulai cepat grafik untuk membuat dan memuat grafik sampel.
Anda harus terbiasa dengan grafik properti dan pemahaman dasar tentang GQL, termasuk struktur hasil dan hasil eksekusi.
Anda perlu menginstal dan menyiapkan alat Azure CLIaz untuk masuk ke organisasi Anda. Contoh baris perintah dalam artikel ini mengasumsikan penggunaan shell baris perintah yang kompatibel dengan POSIX seperti bash.

Authentication

API Kueri GQL memerlukan autentikasi melalui token pembawa.

Sertakan token akses Anda di header Otorisasi setiap permintaan:

Authorization: Bearer <your-access-token>

Secara umum, Anda dapat memperoleh token pembawa menggunakan Pustaka Autentikasi Microsoft (MSAL) atau alur autentikasi lainnya yang kompatibel dengan Microsoft Entra.

Token pembawa umumnya diperoleh melalui dua jalur utama:

Akses yang didelegasikan pengguna

Anda dapat memperoleh token pembawa untuk panggilan layanan yang didelegasikan pengguna dari baris perintah melalui alat Azure CLIaz.

Dapatkan token pembawa untuk panggilan yang didelegasikan pengguna dari baris perintah dengan:

Jalankan az login
Kemudian az account get-access-token --resource https://api.fabric.microsoft.com

Ini menggunakan alat Azure CLIaz.

Saat Anda menggunakan az rest untuk melakukan permintaan, token pembawa diperoleh secara otomatis.

Akses aplikasi

Anda dapat memperoleh token pembawa untuk aplikasi yang terdaftar di Microsoft Entra. Lihat mulai cepat Fabric API untuk detail lebih lanjut.

Titik akhir API

API menggunakan satu titik akhir yang menerima semua operasi kueri:

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

API Query masih dalam versi beta dan tidak direkomendasikan untuk penggunaan produksi. Atur parameter kueri yang diperlukan beta ke true. Parameter lama preview=true tetap didukung untuk kompatibilitas mundur, tetapi digunakan beta=true untuk integrasi baru.

Untuk mendapatkan {workspaceId} ruang kerja, Anda dapat mencantumkan semua ruang kerja yang tersedia menggunakan az rest:

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

Untuk mendapatkan , Anda dapat mencantumkan {graphModelId}semua grafik yang tersedia di ruang kerja menggunakan az rest:

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

Anda dapat menggunakan opsi output Azure CLI untuk memfilter atau memformat respons dari permintaan daftar ini. Opsi-opsi ini berjalan di klien Azure CLI; bukan parameter Query API:

--query "value[?displayName=='My Workspace']" hanya mencantumkan item dengan a displayName dari My Workspace.
--query "value[?starts_with(displayName, 'My')]" hanya mencantumkan item yang displayName dimulai dengan My.
--query "{query}" hanya mencantumkan item yang sesuai dengan JMESPath {query}yang disediakan. Lihat hasil perintah Query Azure CLI untuk sintaks yang didukung.
-o table untuk menghasilkan hasil tabel.

Nota

Lihat bagian tentang menggunakan az-rest atau bagian tentang menggunakan curl untuk cara menjalankan kueri melalui titik akhir API dari shell baris perintah.

Parameter permintaan

Parameter	Tipe	Diperlukan	Description
`beta`	Boolean	Yes	Atur ke `true` untuk menggunakan API Query beta.
`continuationToken`	string	No	Token dari `result.nextPage` saat kueri masih berjalan. Kirimkan teks query yang sama saat Anda menggunakan token.

Tajuk permintaan

Header	Nilai	Diperlukan
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer <token>`	Yes

Format permintaan

Semua permintaan menggunakan HTTP POST dengan payload JSON.

Struktur permintaan dasar

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

Bidang permintaan

Bidang	Tipe	Diperlukan	Description
`query`	string	Yes	Kueri GQL untuk dijalankan

Format Tanggapan

Semua respons untuk permintaan yang berhasil menggunakan status HTTP 200 dengan payload JSON yang berisi status dan hasil eksekusi.

Struktur respons

{
  "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": [...]
  }
}

Objek status

Setiap respons menyertakan objek status dengan informasi eksekusi:

Bidang	Tipe	Description
`code`	string	Kode status API publik lima karakter.
`description`	string	Deskripsi status yang dapat dibaca manusia.
`diagnostics`	objek	Catatan diagnostik rinci, termasuk status GQL-engine kueri kanonik jika tersedia.
`cause`	objek	Objek status penyebab dasar opsional.

Kode status

Kategori utama status.code menggunakan API publik berikut:

00000 - Penyelesaian berhasil dengan setidaknya satu baris.
00001 - Penyelesaian berhasil dengan hasil yang dihilangkan. Disediakan untuk dukungan DDL dan DML di masa depan.
01000 - Kondisi peringatan atau informasi.
02000 - Tidak ada baris yang tersedia saat ini dari kueri yang menghasilkan baris.
42000 - Sintaks, aturan akses, atau kesalahan kueri lain yang dapat diperbaiki pengguna.
50000 - Kesalahan sistem atau tidak diklasifikasikan.

Untuk informasi selengkapnya, lihat referensi kode status GQL.

Rekaman diagnostik

Rekaman diagnostik dapat berisi pasangan kunci-nilai lain yang merinci lebih lanjut objek status. Kunci yang dimulai dengan garis bawah (_) khusus untuk grafik. Standar GQL meresepkan semua kunci lainnya.

Nota

Diagnostik berisi _graphaneGqlStatus GQLSTATUS lima karakter kanonik yang dilaporkan oleh mesin query. Setiap anggota diagnostik dengan awalan garis bawah berisi nilai GQL yang null dikodekan JSON. Misalnya, _graphaneGqlStatus menggunakan STRING, sementara diagnostik klasifikasi kesalahan menggunakan BOOL. Lihat Jenis nilai dan pengodean.

Penyebab

Objek status menyertakan bidang opsional cause saat penyebab yang mendasar diketahui.

Objek status lainnya

Beberapa hasil dapat melaporkan objek status lain sebagai daftar di bidang opsional additionalStatuses .

Status utama adalah kondisi paling kritis yang tercatat. Setiap status tambahan dan sebab bersarang memiliki kode API publik dan diagnostik GQLSTATUS kanonik.

Jenis hasil

Hasil menggunakan pola serikat yang didiskriminasi dengan kind bidang :

Hasil tabel

Untuk kueri yang mengembalikan data tabular:

{
  "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
    }
  ]
}

Kueri yang berjalan lama

Jika sebuah kueri tidak selesai selama permintaan HTTP saat ini, API mengembalikan HTTP 200 dengan kode 02000status publik, tabel kosong, dan token nextPage :

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

Polling untuk penyelesaian dengan mengirim isi permintaan yang sama dan menambahkan token ke URL:

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

Perlakukan nextPage sebagai nilai yang tidak transparan. Enkodekan persentase-nya tepat sekali sesuai RFC 3986 sebelum menggunakannya sebagai continuationToken nilai parameter kueri. Jangan mendekode, memeriksa, atau memodifikasi token.

Lanjutkan sampai respons tidak lagi berisi nextPage. Eksekusi kueri dapat berlangsung hingga 20 menit sejak permintaan awal. Jika melebihi total durasi tersebut, API mengembalikan HTTP 408 dengan kode QueryTimeouterror .

Hasil yang dipotong

Grafik memotong respons kueri ketika representasi biner internalnya melebihi 64 MB. API mengembalikan baris yang sesuai dan menambahkan status ke additionalStatuses. Status tambahan menggunakan kode 01000 publik dan mempertahankan status 01M11 GQL kanonik di _graphaneGqlStatus.

Trunci tidak menghasilkan nextPage token untuk baris yang dihilangkan. Persempit kueri dengan filter, proyeksi spesifik, atau LIMIT, lalu jalankan lagi.

Hasil yang dihilangkan

Skema respons dapat mewakili operasi yang pernyataannya tidak pernah menghasilkan baris, terlepas dari data atau hasil evaluasi. Hasil ini menggunakan kode 00001status :

{
  "kind": "NOTHING"
}

Hasil yang diabaikan ini berbeda dengan tabel tanpa baris. Tabel kosong adalah hasil dari evaluasi kueri yang menghasilkan baris yang saat ini tidak memiliki baris untuk dikembalikan.

Graph menyimpan bentuk hasil dan kode status ini untuk dukungan pernyataan bahasa definisi data (DDL) dan bahasa manipulasi data (DML) di masa depan. Pernyataan kueri saat ini selalu mengembalikan hasil tabel.

Jenis nilai dan pengodean

API menggunakan sistem jenis yang kaya untuk mewakili nilai GQL dengan semantik yang tepat. Format JSON nilai GQL mengikuti pola gabungan yang diskriminasi.

Nota

Format JSON hasil tabular mewujudkan pola serikat yang diskriminasi dengan memisahkan gqlType dan value untuk mencapai representasi yang lebih ringkas. Lihat Pengoptimalan serialisasi tabel.

Struktur nilai

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

Jenis primitif

Jenis GQL	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Boolean JSON asli
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	String UTF-8

Jenis numerik

Jenis bilangan bulat

Jenis GQL	Jangkauan	Serialisasi JSON	Example
`INT64`	-2⁶³ ke 2⁶³-1	Angka atau string*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 hingga 2⁶⁴-1	Angka atau string*	`{"gqlType": "UINT64", "value": 18467}`

Bilangan bulat besar di luar rentang aman JavaScript (-9.007.199.254.740.991 hingga 9.007.199.254.740.991) diserialisasikan sebagai string:

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

Jenis titik mengambang

Jenis GQL	Jangkauan	Serialisasi JSON	Example
`FLOAT64`	Biner IEEE 75464	Nomor atau string JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

Nilai floating-point mendukung nilai khusus IEEE 754:

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

Jenis temporal

Jenis temporal yang didukung menggunakan format string ISO 8601:

Jenis GQL	Rancangan	Example
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Jenis referensi elemen Grafik

Jenis GQL	Description	Example
`NODE`	Referensi simpul grafik	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Referensi tepi grafik	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Jenis kompleks

Jenis kompleks terdiri dari nilai GQL lainnya.

Lists

Daftar berisi array nilai nullable dengan jenis elemen yang konsisten:

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

Jenis daftar khusus:

LIST<ANY> - Jenis campuran (setiap elemen mencakup info jenis lengkap)
LIST<NULL> - Hanya nilai null yang diizinkan
LIST<NOTHING> - Array selalu kosong

Paths

Jalur dikodekan sebagai daftar nilai referensi elemen grafik.

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

Lihat Pengoptimalan serialisasi tabel.

Pengoptimalan serialisasi tabel

Untuk hasil tabel, serialisasi nilai dioptimalkan berdasarkan informasi jenis kolom:

Jenis yang diketahui - Hanya nilai mentah yang diserialisasikan
Kolom APA PUN - Objek nilai penuh dengan jenis diskriminator

{
  "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"}
    }
  ]
}

Penanganan kesalahan

Kesalahan transportasi

Status HTTP dan status GQL menggambarkan lapisan respons yang berbeda:

HTTP Status	Meaning
200	API memproses permintaan tersebut. Periksa `status.code` karena hasilnya dapat mewakili keberhasilan, tidak ada baris, kueri yang masih berjalan, atau kesalahan kueri yang dapat diperbaiki pengguna.
408	Eksekusi kueri melebihi total timeout 20 menit. Kode errornya adalah `QueryTimeout`.
429	Batas tarif layanan terlampaui. Tunggu durasi di `Retry-After` header sebelum mencoba ulang.
499	Penelepon membatalkan permintaan tersebut. Kode errornya adalah `ClientCancelled`.
4xx atau 5xx lainnya	Permintaan atau layanan gagal sebelum mengembalikan hasil eksekusi GQL. Periksa respons kesalahan HTTP.

Kesalahan aplikasi

Kesalahan tingkat aplikasi dapat mengembalikan HTTP 200 dengan informasi kesalahan dalam objek status. Misalnya, division by zero menggunakan kode 42000 API publik dan mempertahankan status GQLSTATUS 22012 kanonik dalam catatan diagnostik:

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

Pemeriksaan status

Untuk menentukan hasil umum, periksa informasi publik status.code. Gunakan _graphaneGqlStatus ketika aplikasi Anda perlu membedakan kondisi mesin kueri tertentu, seperti numerik overflow (22003) dari pembagian dengan nol ().22012

Contoh lengkap dengan az rest

Jalankan kueri menggunakan az rest perintah untuk menghindari harus mendapatkan token pembawa secara manual, seperti:

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

Contoh lengkap dengan curl

Contoh di bagian ini menggunakan curl alat untuk melakukan permintaan HTTPS dari shell.

Kami berasumsi Anda memiliki token akses yang valid yang disimpan dalam variabel shell, seperti:

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

Petunjuk / Saran

Lihat bagian tentang autentikasi untuk cara mendapatkan token pembawa yang valid.

Jalankan kueri seperti itu:

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

Praktik terbaik

Ikuti praktik terbaik ini saat menggunakan GQL Query API.

Penanganan kesalahan

Selalu periksa kode status - Jangan asumsikan keberhasilan berdasarkan HTTP 200.
Uraikan detail kesalahan - Gunakan diagnostik dan menyebabkan rantai untuk penelusuran kesalahan.

Keamanan

Gunakan HTTPS - Jangan pernah mengirim token autentikasi melalui koneksi yang tidak terenkripsi.
Putar token - Terapkan penyegaran token yang tepat dan penanganan kedaluwarsa.
Validasi input - Validasi dan keluarkan dengan benar nilai yang disediakan pengguna yang dimasukkan aplikasi Anda ke dalam teks kueri.

Representasi nilai

Tangani nilai bilangan bulat besar - Bilangan bulat dikodekan sebagai string jika tidak dapat direpresentasikan sebagai angka JSON secara asli.
Menangani nilai floating-point khusus - API menserialisasi infinitas positif, tak hingga negatif, bukan-angka, dan nol negatif sebagai "Inf", "-Inf", "NaN", dan "-0".
Menangani nilai null - JSON null mewakili GQL null.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-29

Referensi API Kueri GQL

Gambaran Umum

Fitur utama

Prasyarat

Authentication

Akses yang didelegasikan pengguna

Akses aplikasi

Titik akhir API

Parameter permintaan

Tajuk permintaan

Format permintaan

Struktur permintaan dasar

Bidang permintaan

Format Tanggapan

Struktur respons

Objek status

Kode status

Rekaman diagnostik

Penyebab

Objek status lainnya

Jenis hasil

Hasil tabel

Kueri yang berjalan lama

Hasil yang dipotong

Hasil yang dihilangkan

Jenis nilai dan pengodean

Struktur nilai

Jenis primitif

Jenis numerik

Jenis bilangan bulat

Jenis titik mengambang

Jenis temporal

Jenis referensi elemen Grafik

Jenis kompleks

Lists

Paths

Pengoptimalan serialisasi tabel

Penanganan kesalahan

Kesalahan transportasi

Kesalahan aplikasi

Pemeriksaan status

Contoh lengkap dengan az rest

Contoh lengkap dengan curl

Praktik terbaik

Penanganan kesalahan

Keamanan

Representasi nilai

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: