การอ้างอิง GQL Query API

เรียกใช้คิวรี GQL กับกราฟคุณสมบัติในกราฟใน Microsoft Fabric โดยใช้ RESTful HTTP API การอ้างอิงนี้อธิบายสัญญา HTTP: คําขอและรูปแบบการตอบกลับ การรับรองความถูกต้อง การเข้ารหัสผลลัพธ์ JSON และการจัดการข้อผิดพลาด

สําคัญ

บทความนี้ใช้ชุดข้อมูลกราฟตัวอย่างเครือข่ายสังคมโดยเฉพาะ

Overview

GQL Query API เปิดเผย REST endpoint ที่รับคําสั่ง GQL เป็น JSON payload และส่งคืนผลลัพธ์ที่มีโครงสร้างและชนิดข้อมูล รองรับการสํารวจต่อเนื่องสําหรับคําค้นที่ไม่เสร็จสิ้นในช่วงคําขอเริ่มต้น

คุณลักษณะสำคัญ

จุดสิ้นสุดเดียว - การดําเนินการทั้งหมดใช้ HTTP POST ไปยัง URL หนึ่ง
ตาม JSON - คําขอและส่วนข้อมูลการตอบสนองใช้ JSON ด้วยการเข้ารหัสที่หลากหลายของค่า GQL ที่พิมพ์
การตรวจสอบต่อเนื่อง - การค้นหาที่ดําเนินการยาวนานสามารถดําเนินต่อไปได้ข้ามคําขอ HTTP หลายรายการ
ประเภทปลอดภัย - การพิมพ์ที่เข้ากันได้กับ GQL ที่แข็งแกร่งกับสหภาพแรงงานที่แยกแยะสําหรับการแสดงค่า

ข้อกําหนดเบื้องต้น

คุณจําเป็นต้องมีกราฟที่ประกอบด้วยข้อมูล รวมถึงโหนดและขอบ (ความสัมพันธ์) ดู กราฟเริ่มต้นด่วน เพื่อสร้างและโหลดกราฟตัวอย่าง
คุณควรจะคุ้นเคยกับกราฟคุณสมบัติและความเข้าใจพื้นฐานของ GQL รวมถึงโครงสร้างของผลลัพธ์การดําเนินการและผลลัพธ์
คุณจําเป็นต้องติดตั้งและตั้งค่าเครื่องมือ Azure CLIaz เพื่อลงชื่อเข้าใช้องค์กรของคุณ ตัวอย่างบรรทัดคําสั่งในบทความนี้จะถือว่าใช้เชลล์บรรทัดคําสั่งที่เข้ากันได้กับ POSIX เช่น แบช

การรับรองความถูกต้อง

GQL Query API จําเป็นต้องรับรองความถูกต้องผ่านโทเค็นแบบแบเรอร์

รวมโทเค็นการเข้าถึงของคุณในส่วนหัวการให้สิทธิ์ของคําขอทั้งหมด:

Authorization: Bearer <your-access-token>

โดยทั่วไป คุณสามารถรับโทเค็นแบเรอร์โดยใช้ Microsoft Authentication Library (MSAL) หรือโฟลว์การรับรองความถูกต้องอื่น ๆ ที่เข้ากันได้กับ Microsoft Entra

โทเค็นแบเรอร์มักได้รับผ่านเส้นทางหลักสองเส้นทาง:

การเข้าถึงที่มอบหมายโดยผู้ใช้

คุณสามารถขอรับโทเค็นแบเรอร์สําหรับการเรียกใช้บริการที่ได้รับมอบหมายจากบรรทัดคําสั่งผ่านเครื่องมือ Azure CLIaz ได้

รับโทเค็นแบเรอร์สําหรับการเรียกใช้ที่มอบหมายโดยผู้ใช้จากบรรทัดคําสั่งโดย:

เรียกใช้ az login
แล้ว az account get-access-token --resource https://api.fabric.microsoft.com

ซึ่งใช้เครื่องมือ Azure CLIaz

เมื่อคุณใช้ az rest สําหรับการดําเนินการตามคําขอ จะได้รับโทเค็นแบบแบเรอร์โดยอัตโนมัติ

การเข้าถึงแอปพลิเคชัน

คุณสามารถรับโทเค็นแบเรอร์สําหรับแอปพลิเคชันที่ลงทะเบียนไว้ใน Microsoft Entra ได้ ดูการ เริ่มต้นใช้งานด่วน Fabric API สําหรับรายละเอียดเพิ่มเติม

จุดสิ้นสุด API

API ใช้จุดสิ้นสุดเดียวที่ยอมรับการดําเนินการคิวรีทั้งหมด:

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

Query API ยังอยู่ในช่วงเบต้าและไม่แนะนําให้ใช้งานในระบบผลิตจริง ตั้งค่าพารามิเตอร์การค้นหาที่ต้องการ beta เป็น true. พารามิเตอร์เก่า preview=true ยังคงรองรับสําหรับความเข้ากันได้ย้อนหลัง แต่ใช้ beta=true สําหรับการรวมระบบใหม่

หากต้องการรับ {workspaceId} สําหรับพื้นที่ทํางานของคุณ คุณสามารถแสดงพื้นที่ทํางานที่พร้อมใช้งานทั้งหมดโดยใช้ az rest:

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

หากต้องการรับ {graphModelId}คุณสามารถแสดงรายการกราฟที่พร้อมใช้งานทั้งหมดในพื้นที่ทํางานโดยใช้ az rest:

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

คุณสามารถใช้ตัวเลือกผลลัพธ์ของ Azure CLI เพื่อกรองหรือจัดรูปแบบคําตอบจากคําขอรายการเหล่านี้ ตัวเลือกเหล่านี้ทํางานในไคลเอนต์ Azure CLI; ไม่ใช่พารามิเตอร์ API ของ Query:

--query "value[?displayName=='My Workspace']"แสดงรายการเฉพาะรายการที่มีค่าdisplayNameMy Workspace
--query "value[?starts_with(displayName, 'My')]" แสดงรายการเฉพาะรายการที่ displayName ขึ้นต้นด้วย My.
--query "{query}" แสดงรายการเฉพาะรายการที่ตรงกับ JMESPath {query}ที่ให้มาเท่านั้น ดูผลลัพธ์คําสั่ง Query Azure CLI สําหรับไวยากรณ์ที่รองรับ
-o table เพื่อสร้างผลลัพธ์ของตาราง

Note

ดู ส่วนบนโดยใช้ az-rest หรือ ส่วนบนโดยใช้ curl สําหรับวิธีการดําเนินการคิวรีผ่านจุดสิ้นสุด API จากเชลล์บรรทัดคําสั่ง

พารามิเตอร์คิวรี

พารามิเตอร์	ประเภท	Required	คำอธิบาย
`beta`	บูลีน	ใช่	ตั้งค่าให้ `true` ใช้ Query API เบต้า
`continuationToken`	สตริง	ไม่ใช่	โทเค็นตั้งแต่ `result.nextPage` เมื่อคําสั่งค้นหายังคงทํางานอยู่ ส่งข้อความคําค้นหาเดียวกันเมื่อใช้โทเค็น

ส่วนหัวของคำร้อง

ส่วนหัว	ค่า	Required
`Content-Type`	`application/json`	ใช่
`Accept`	`application/json`	ใช่
`Authorization`	`Bearer <token>`	ใช่

รูปแบบคําขอ

คําขอทั้งหมดใช้ HTTP POST กับส่วนข้อมูล JSON

โครงสร้างคําขอพื้นฐาน

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

ร้องขอเขตข้อมูล

เขตข้อมูล	ประเภท	Required	คำอธิบาย
`query`	สตริง	ใช่	คิวรี GQL เพื่อดําเนินการ

รูปแบบการตอบ

การตอบสนองทั้งหมดสําหรับคําขอที่สําเร็จใช้สถานะ HTTP 200 กับส่วนข้อมูล JSON ที่มีสถานะการดําเนินการและผลลัพธ์

โครงสร้างการตอบสนอง

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

ออบเจ็กต์สถานะ

การตอบสนองทุกครั้งมีออบเจ็กต์สถานะพร้อมข้อมูลการดําเนินการ:

เขตข้อมูล	ประเภท	คำอธิบาย
`code`	สตริง	รหัสสถานะ API สาธารณะ 5 ตัวอักษร
`description`	สตริง	คําอธิบายสถานะที่อ่านได้โดยมนุษย์
`diagnostics`	ออบเจ็กต์	ระเบียนวินิจฉัยโดยละเอียด รวมถึง GQLSTATUS ของเครื่องมือค้นหามาตรฐานเมื่อมีให้ใช้งาน
`cause`	ออบเจ็กต์	วัตถุสถานะสาเหตุพื้นฐานที่เป็นทางเลือก

รหัสสถานะ

หลักใช้ status.code หมวดหมู่ API สาธารณะเหล่านี้:

00000 - การกรอกข้อมูลสําเร็จอย่างน้อยหนึ่งแถว
00001 - สําเร็จโดยตัดผลลัพธ์ออก สงวนไว้สําหรับการรองรับ DDL และ DML ในอนาคต
01000 - เงื่อนไขเตือนหรือข้อมูล.
02000 - ขณะนี้ยังไม่มีแถวใดที่ว่างจากคําสั่งที่สร้างแถว
42000 - ข้อผิดพลาดไวยากรณ์, กฎการเข้าถึง หรือข้อผิดพลาดอื่น ๆ ที่ผู้ใช้สามารถแก้ไขได้
50000 - ข้อผิดพลาดของระบบหรือไม่ได้จัดประเภท

สําหรับข้อมูลเพิ่มเติม โปรดดูการอ้างอิงรหัสสถานะ GQL

บันทึกการวินิจฉัย

บันทึกการวินิจฉัยสามารถประกอบด้วยคู่ค่าคีย์อื่น ๆ ที่เพิ่มเติมรายละเอียดวัตถุสถานะ คีย์ที่เริ่มต้นด้วยเครื่องหมายขีดล่าง (_) เป็นคีย์เฉพาะสําหรับกราฟ มาตรฐาน GQL กําหนดคีย์อื่น ๆ ทั้งหมด

Note

การวินิจฉัยประกอบด้วย _graphaneGqlStatus GQLSTATUS แบบ canonical ห้าตัวอักษรที่รายงานโดยเครื่องมือค้นหา สมาชิกวินิจฉัยที่มีขีดล่างนําหน้าทุกตัวจะมี null ค่า GQL ที่เข้ารหัสด้วย JSON หรือค่า ตัวอย่างเช่น _graphaneGqlStatus ใช้ STRING, ในขณะที่การวินิจฉัยการจําแนกข้อผิดพลาดใช้ BOOL. ดู ชนิดค่าและการเข้ารหัส

สาเหตุ

ออบเจ็กต์สถานะรวมถึงเขตข้อมูลทางเลือก cause เมื่อทราบสาเหตุพื้นฐาน

วัตถุสถานะอื่น ๆ

ผลลัพธ์บางรายการสามารถรายงานวัตถุสถานะอื่น ๆ เป็นรายการในช่องเลือกได้additionalStatuses

สถานะหลักคือภาวะที่วิกฤตที่สุดที่บันทึกไว้ สถานะเพิ่มเติมและสาเหตุที่ซ้อนกันแต่ละตัวจะมีโค้ด API สาธารณะและ GQLSTATUS วินิจฉัยแบบมาตรฐานของตัวเอง

ชนิดผลลัพธ์

ผลลัพธ์ใช้รูปแบบยูเนียนที่แยกแยะกับ kind เขตข้อมูล:

ผลลัพธ์ตาราง

สําหรับคิวรีที่ส่งกลับข้อมูลแบบตาราง:

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

คิวรีที่ใช้เวลานาน

หากคําสั่งไม่เสร็จสิ้นในระหว่างคําขอ HTTP ปัจจุบัน API จะคืนค่า HTTP 200 พร้อมรหัส 02000สถานะสาธารณะ ตารางว่าง และ nextPage โทเค็น:

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

ตรวจสอบเพื่อเสร็จสิ้นโดยส่งเนื้อหาคําขอเดียวกันและเพิ่มโทเค็นลงใน URL:

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

ถือว่า nextPage เป็นค่าที่ไม่โปร่งใส เข้ารหัสเปอร์เซ็นต์เพียงครั้งเดียวตาม RFC 3986 ก่อนใช้เป็น continuationToken ค่าพารามิเตอร์คําสั่ง query อย่าถอดรหัส ตรวจสอบ หรือแก้ไขโทเค็น

ดําเนินการต่อไปจนกว่าคําตอบจะไม่มี nextPage. การดําเนินการค้นหาสามารถดําเนินต่อไปได้นานสูงสุด 20 นาทีนับจากคําขอเริ่มต้น หากเกินระยะเวลารวมดังกล่าว API จะคืนค่า HTTP 408 พร้อมรหัส QueryTimeoutข้อผิดพลาด

ผลลัพธ์ที่ถูกตัดทอน

กราฟจะตัดทอนการตอบกลับคําค้นเมื่อการแทนค่าไบนารีภายในเกิน 64 MB API จะคืนแถวที่พอดีและเพิ่มสถานะให้กับadditionalStatuses สถานะเพิ่มเติมใช้รหัส 01000 สาธารณะและรักษาสถานะ 01M11 GQL แบบมาตรฐานใน _graphaneGqlStatus.

การตัดทอนจะไม่สร้าง nextPage โทเค็นสําหรับแถวที่ถูกละเว้น จํากัดคิวรีด้วยตัวกรอง, การฉายภาพเฉพาะ หรือ LIMIT, แล้วรันอีกครั้ง

ผลลัพธ์ที่ถูกละเว้น

สคีมาการตอบสนองสามารถแทนการดําเนินการที่คําสั่งจะไม่สร้างแถวโดยไม่ขึ้นกับข้อมูลหรือผลลัพธ์การประเมิน ผลลัพธ์นี้ใช้รหัส 00001สถานะ :

{
  "kind": "NOTHING"
}

ผลลัพธ์ที่ถูกละเว้นนี้แตกต่างจากตารางที่ไม่มีแถว ตารางว่างคือผลลัพธ์จากการประเมินคําสั่งที่สร้างแถวซึ่งขณะนี้ยังไม่มีแถวให้คืนค่า

กราฟสงวนรูปแบบผลลัพธ์และรหัสสถานะนี้ไว้สําหรับการรองรับคําสั่ง Data Definition Language (DDL) และ Data Manipulation Language (DML) ในอนาคต คําสั่งค้นหาปัจจุบันจะคืนผลลัพธ์ของตารางเสมอ

ชนิดค่าและการเข้ารหัส

API ใช้ระบบประเภทที่หลากหลายเพื่อแสดงค่า GQL พร้อมความหมายที่แม่นยํา รูปแบบ JSON ของค่า GQL เป็นไปตามรูปแบบยูเนียนที่แยกแยะแล้ว

Note

รูปแบบ JSON ของผลลัพธ์แบบตารางตระหนักถึงรูปแบบยูเนียนที่แยกแยะแล้วแยก gqlType และ value เพื่อให้ได้ตัวแทนที่กะทัดรัดมากขึ้น ดูการปรับการซีเรียลของตารางให้เหมาะสม

โครงสร้างค่า

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

ชนิดดั้งเดิม

ชนิดของ GQL	ตัวอย่าง	คำอธิบาย
`BOOL`	`{"gqlType": "BOOL", "value": true}`	บูลีน JSON แบบดั้งเดิม
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	สตริง UTF-8

ชนิดตัวเลข

ชนิดจํานวนเต็ม

ชนิดของ GQL	ช่วง	การอนุกรม JSON	ตัวอย่าง
`INT64`	-2⁶³ ถึง 2⁶³-1	ตัวเลขหรือสตริง*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 ถึง 2⁶⁴-1	ตัวเลขหรือสตริง*	`{"gqlType": "UINT64", "value": 18467}`

จํานวนเต็มขนาดใหญ่ภายนอกช่วงที่ปลอดภัยของ JavaScript (-9,007,199,254,740,991 ถึง 9,007,199,254,740,991) เป็นสตริงแบบอนุกรม:

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

ชนิดจุดทศนิยมลอยตัว

ชนิดของ GQL	ช่วง	การอนุกรม JSON	ตัวอย่าง
`FLOAT64`	IEEE 754 Binary64	หมายเลขหรือสตริง JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

ค่าเลขทศนิยมสนับสนุนค่าพิเศษ IEEE 754:

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

ชนิดทางโลก

ชนิดเชิงเวลาที่ได้รับการสนับสนุนใช้รูปแบบสตริง ISO 8601:

ชนิดของ GQL	รูปแบบ	ตัวอย่าง
`ZONED DATETIME`	YYYY-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

ชนิดการอ้างอิงองค์ประกอบของกราฟ

ชนิดของ GQL	คำอธิบาย	ตัวอย่าง
`NODE`	การอ้างอิงโหนดกราฟ	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	การอ้างอิงขอบกราฟ	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

ชนิดที่ซับซ้อน

ชนิดที่ซับซ้อนประกอบด้วยค่า GQL อื่น ๆ

รายการ

รายการมีอาร์เรย์ของค่าที่สามารถเป็น null ได้ซึ่งมีชนิดองค์ประกอบที่สอดคล้องกัน:

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

ชนิดรายการพิเศษ:

LIST<ANY> - ประเภทผสม (แต่ละองค์ประกอบประกอบด้วยข้อมูลประเภทเต็ม)
LIST<NULL> - อนุญาตเฉพาะค่า null เท่านั้น
LIST<NOTHING> - อาร์เรย์ที่ว่างเปล่าเสมอ

เส้น ทาง

เส้นทางจะถูกเข้ารหัสเป็นรายการของค่าการอ้างอิงองค์ประกอบกราฟ

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

ดูการปรับการซีเรียลของตารางให้เหมาะสม

การปรับตารางให้เป็นอนุกรมให้เหมาะสม

สําหรับผลลัพธ์ตาราง ค่าการจัดเรียงแบบอนุกรมถูกปรับให้เหมาะสมโดยยึดตามข้อมูลชนิดคอลัมน์:

ชนิดที่ทราบ - เฉพาะค่าดิบเท่านั้นที่จะถูกทําให้เป็นอนุกรม
คอลัมน์ใดก็ตาม - วัตถุค่าเต็มที่มีชนิดตัวแยกแยะ

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

การจัดการข้อผิดพลาด

ข้อผิดพลาดในการส่ง

สถานะ HTTP และสถานะ GQL อธิบายชั้นต่าง ๆ ของการตอบกลับ:

สถานะ HTTP	ความหมาย
200	API ได้ประมวลผลคําขอแล้ว ตรวจสอบ `status.code` เพราะผลลัพธ์อาจแสดงถึงความสําเร็จ ไม่มีแถว คําสั่งที่ยังดําเนินการอยู่ หรือข้อผิดพลาดคําสั่งที่ผู้ใช้แก้ไขได้
408	การประมวลผลคําสั่งเกินเวลารวม 20 นาที รหัสข้อผิดพลาดคือ `QueryTimeout`.
429	เกินขีดจํากัดอัตราการบริการ รอระยะเวลาในส่วน `Retry-After` หัวก่อนลองใหม่
499	ผู้โทรยกเลิกคําขอ รหัสข้อผิดพลาดคือ `ClientCancelled`.
4xx หรือ 5xx อื่น ๆ	คําขอหรือบริการล้มเหลวก่อนที่จะส่งผลลัพธ์การดําเนินการ GQL กลับคืนมา ตรวจสอบการตอบสนองข้อผิดพลาด HTTP

ข้อผิดพลาดของแอปพลิเคชัน

ข้อผิดพลาดระดับแอปพลิเคชันสามารถส่งคืน HTTP 200 พร้อมข้อมูลข้อผิดพลาดในวัตถุสถานะ ตัวอย่างเช่น การหารด้วยศูนย์ใช้โค้ด 42000 API สาธารณะและรักษาสถานะ 22012 GQL แบบมาตรฐานในระเบียนวินิจฉัย:

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

การตรวจสอบสถานะ

เพื่อกําหนดผลลัพธ์โดยรวม ให้ตรวจสอบข้อมูลสาธารณะstatus.code ใช้ _graphaneGqlStatus เมื่อแอปพลิเคชันของคุณต้องแยกแยะเงื่อนไขเฉพาะของเครื่องมือค้นหา เช่น การล้นตัวเลข (22003) กับการหารด้วยศูนย์ (22012)

ตัวอย่างที่สมบูรณ์ด้วย az rest

เรียกใช้คิวรีโดยใช้ az rest คําสั่ง เพื่อหลีกเลี่ยงการได้รับโทเค็นแบบแบเรอร์ด้วยตนเอง เช่น:

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

ตัวอย่างในส่วนนี้ใช้ curl เครื่องมือสําหรับการดําเนินการคําขอ HTTPS จากเชลล์

เราสมมติว่าคุณมีโทเค็นการเข้าถึงที่ถูกต้องที่จัดเก็บไว้ในตัวแปรเชลล์ เช่น:

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

เคล็ดลับ

ดู ส่วนในการรับรองความถูกต้อง สําหรับวิธีการขอรับโทเค็นแบบแบเรอร์ที่ถูกต้อง

เรียกใช้คิวรีเช่นนั้น:

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

แนวทางปฏิบัติที่ดีที่สุด

ปฏิบัติตามแนวทางปฏิบัติที่ดีที่สุดเหล่านี้เมื่อใช้ GQL Query API

การจัดการข้อผิดพลาด

ตรวจสอบรหัสสถานะเสมอ - อย่าคาดเดาความสําเร็จโดยยึดตาม HTTP 200
แยกวิเคราะห์รายละเอียดข้อผิดพลาด - ใช้การวินิจฉัยและสาเหตุของการดีบัก

Security

ใช้ HTTPS - อย่าส่งโทเค็นการรับรองความถูกต้องผ่านการเชื่อมต่อที่ไม่ได้เข้ารหัสลับ
โทเค็นการหมุน - ใช้การจัดการการรีเฟรชโทเค็นและวันหมดอายุที่เหมาะสม
ตรวจสอบข้อมูลนําเข้า - ตรวจสอบและหลบหนีค่าที่ผู้ใช้ให้ไว้ซึ่งแอปพลิเคชันของคุณแทรกเข้าไปในข้อความค้นหาอย่างถูกต้อง

การแสดงค่า

จัดการค่าจํานวนเต็มขนาดใหญ่ - จํานวนเต็มจะถูกเข้ารหัสเป็นสตริงหากไม่สามารถแสดงเป็นตัวเลข JSON ได้แบบเดิม
จัดการค่าทศนิยมลอยตัวพิเศษ - API จะทําการอนุกรมค่าเป็นอนันต์บวก ลบอนันต์ ไม่ใช่จํานวน และลบศูนย์เป็น "Inf", "-Inf""NaN"และ"-0"
จัดการค่า null - Null JSON แทนค่า Null GQL

คำติชม

หน้านี้มีประโยชน์หรือไม่

อัปเดตล่าสุดเมื่อ 2026-09-29

การอ้างอิง GQL Query API

Overview

คุณลักษณะสำคัญ

ข้อกําหนดเบื้องต้น

การรับรองความถูกต้อง

การเข้าถึงที่มอบหมายโดยผู้ใช้

การเข้าถึงแอปพลิเคชัน

จุดสิ้นสุด API

พารามิเตอร์คิวรี

ส่วนหัวของคำร้อง

รูปแบบคําขอ

โครงสร้างคําขอพื้นฐาน

ร้องขอเขตข้อมูล

รูปแบบการตอบ

โครงสร้างการตอบสนอง

ออบเจ็กต์สถานะ

รหัสสถานะ

บันทึกการวินิจฉัย

สาเหตุ

วัตถุสถานะอื่น ๆ

ชนิดผลลัพธ์

ผลลัพธ์ตาราง

คิวรีที่ใช้เวลานาน

ผลลัพธ์ที่ถูกตัดทอน

ผลลัพธ์ที่ถูกละเว้น

ชนิดค่าและการเข้ารหัส

โครงสร้างค่า

ชนิดดั้งเดิม

ชนิดตัวเลข

ชนิดจํานวนเต็ม

ชนิดจุดทศนิยมลอยตัว

ชนิดทางโลก

ชนิดการอ้างอิงองค์ประกอบของกราฟ

ชนิดที่ซับซ้อน

รายการ

เส้น ทาง

การปรับตารางให้เป็นอนุกรมให้เหมาะสม

การจัดการข้อผิดพลาด

ข้อผิดพลาดในการส่ง

ข้อผิดพลาดของแอปพลิเคชัน

การตรวจสอบสถานะ

ตัวอย่างที่สมบูรณ์ด้วย az rest

ตัวอย่างที่เสร็จสมบูรณ์ด้วย curl

แนวทางปฏิบัติที่ดีที่สุด

การจัดการข้อผิดพลาด

Security

การแสดงค่า

เนื้อหาที่เกี่ยวข้อง

คำติชม

แหล่งทรัพยากรเพิ่มเติม