Referensi API Kueri GQL

Nota

Fitur ini saat ini dalam pratinjau publik. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan tidak disarankan untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi selengkapnya, lihat Ketentuan Penggunaan Supplemental untuk Pratinjau Microsoft Azure.

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 adalah titik akhir tunggal (RPC melalui HTTP) yang menerima kueri GQL sebagai payload JSON dan mengembalikan hasil terstruktur dan diketik. API tanpa status, menangani autentikasi, dan menyediakan pelaporan kesalahan yang komprehensif.

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.
  • Stateless - Tidak ada status sesi yang diperlukan antar permintaan.
  • 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 Microsoft Authentication Library (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?preview=true

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 {graphId}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 lebih banyak parameter untuk mempersempit hasil kueri lebih lanjut:

  • --query 'value[?displayName=='My Workspace'] untuk mencantumkan hanya item dengan displayName dari My Workspace.
  • --query 'value[starts_with(?displayName='My')] untuk mencantumkan hanya item yang displayName dimulai dengan My.
  • --query '{query}' untuk hanya mencantumkan item yang cocok dengan JMESPath {query}yang disediakan . Lihat dokumentasi Azure CLI tentang JMESPath mengenai sintaks yang didukung untuk {query}.
  • -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.

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": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "result": {
    "kind": "TABLE",
    "columns": [...],
    "data": [...]
  }
}

Objek status

Setiap respons menyertakan objek status dengan informasi eksekusi:

Bidang Tipe Description
code string kode status enam karakter (000000 = berhasil)
description string Pesan status yang dapat dibaca manusia
diagnostics objek Rekaman diagnostik terperinci
cause objek Objek status penyebab mendasar opsional

Kode status

Kode status mengikuti pola hierarkis:

  • 00xxxx - Keberhasilan lengkap
  • 01xxxx - Berhasil dengan peringatan
  • 02xxxx - Berhasil tanpa data
  • 03xxxx - Berhasil dengan informasi
  • 04xxxx dan lebih tinggi - Kesalahan dan kondisi pengecualian

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

Nilai dalam catatan diagnostik kunci khusus untuk grafik adalah nilai GQL yang dikodekan JSON. 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

Jika demikian, maka objek status utama selalu ditentukan menjadi objek status paling penting (seperti kondisi pengecualian) seperti yang ditentukan oleh standar GQL.

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

Hasil yang dihilangkan

Untuk operasi yang tidak mengembalikan data (misalnya, pembaruan katalog dan/atau data):

{
  "kind": "NOTHING"
}

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
{
  "columns": [
    {"name": "name", "gqlType": "STRING", "jsonType": "string"},
    {"name": "mixed", "gqlType": "ANY", "jsonType": "unknown"}
  ],
  "data": [
    {
      "name": "Alice",
      "mixed": {"gqlType": "INT32", "value": 42}
    }
  ]
}

Penanganan kesalahan

Kesalahan transportasi

Kesalahan transportasi jaringan dan HTTP mengakibatkan kode status kesalahan HTTP standar (4xx, 5xx).

Kesalahan aplikasi

Kesalahan tingkat aplikasi selalu mengembalikan HTTP 200 dengan informasi kesalahan di objek status:

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

Pemeriksaan status

Untuk menentukan keberhasilan, periksa kode status:

  • Kode dimulai dengan 00, 01, 02, 03 menunjukkan keberhasilan (dengan kemungkinan peringatan)
  • Semua kode lain menunjukkan kesalahan

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

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

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 - Bersihkan dan lepaskan parameter kueri yang disediakan pengguna dengan benar yang disuntikkan ke dalam kueri.

Representasi nilai

  • Tangani nilai bilangan bulat besar - Bilangan bulat dikodekan sebagai string jika tidak dapat direpresentasikan sebagai angka JSON secara asli.
  • Menangani nilai titik mengambang khusus - Nilai floating-point yang dikembalikan dari kueri bisa berupa Infinitynilai , , -Infinityatau NaN (bukan angka).
  • Menangani nilai null - JSON null mewakili GQL null.

Konten terkait

  • Last updated on