GQL 查詢 API 參考

備註

這項功能目前處於公開預覽狀態。此預覽版是在沒有服務等級協定的情況下提供，不建議用於生產工作負載。可能不支援特定功能，或可能已經限制功能。欲了解更多資訊，請參閱Microsoft Azure預覽補充使用條款。

在 Microsoft Fabric 中，使用 RESTful HTTP API 對圖形中的屬性圖執行 GQL 查詢。本參考說明 HTTP 合約：要求和回應格式、驗證、JSON 結果編碼和錯誤處理。

這很重要

本文僅使用社群網路範例圖集。

概觀

GQL 查詢 API 是單一端點（RPC over HTTP），可接受 GQL 查詢作為 JSON 承載，並傳回結構化的類型化結果。該 API 是無狀態的，處理身份驗證並提供全面的錯誤報告。

主要功能

單一端點 - 所有作業都會使用HTTP POST到一個URL。
以 JSON 為基礎 - 請求和回應承載使用 JSON 和類型化 GQL 值的豐富編碼。
無狀態 - 請求之間不需要工作階段狀態。
類型安全 - 強而有力的、與 GQL 相容的類型，具有區別的聯集以進行值表示。

先決條件

你需要一個包含資料的圖，包括節點和邊（關係）。請參閱圖表快速入門，以建立和載入範例圖表。
您應該熟悉屬性圖並對 GQL 有基本的了解，包括執行結果和結果的結構。
你需要安裝並設定 Azure CLI 工具 az 才能登入你的組織。本文中的命令列範例假設使用與 POSIX 相容的命令列 shell，例如 bash。

Authentication

GQL 查詢 API 需要透過持有人權杖進行驗證。

將您的存取權杖包含在每個請求的授權標頭中：

Authorization: Bearer <your-access-token>

一般而言，你可以使用 Microsoft Authentication Library（MSAL）或其他與 Microsoft Entra相容的認證流程取得持有憑證。

不記名代幣通常透過兩大途徑取得：

使用者委派的存取權

你可以透過 Azure CLI 工具，從命令列取得使用者委派服務呼叫的承載憑證。

透過以下方式，從命令列取得使用者委派呼叫的持有人權杖：

az login執行
然後 az account get-access-token --resource https://api.fabric.microsoft.com

此工具使用Azure CLI工具az。

當您用於 az rest 執行請求時，會自動取得持有人權杖。

應用程式存取

你可以為在 Microsoft Entra 註冊的應用程式取得持有人代幣。如需詳細資訊，請參閱 Fabric API 快速入門。

API 端點

API 使用接受所有查詢作業的單一端點：

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

若要取得工作區的， {workspaceId} 您可以使用下列方式列出 az rest所有可用的工作區：

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

若要取得 {graphId}，您可以使用下列方式列出 az rest工作區中所有可用的圖表：

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

您可以使用更多參數來進一步縮小查詢結果的範圍：

--query 'value[?displayName=='My Workspace']僅列出具有的displayNameMy Workspace項目。
--query 'value[starts_with(?displayName='My')]僅列出以開頭的displayNameMy項目。
--query '{query}' 僅列出符合所提供 JMESPath {query}的項目。請參閱 JMESPath 上的 Azure CLI 文件，了解支援的語法。
-o table 用於產生表格結果。

備註

請參閱使用 az-rest 一節或使用 curl 一節，以瞭解如何從命令列殼層透過 API 端點執行查詢。

請求標頭

Header	價值觀	為必填項目
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer <token>`	Yes

要求格式

所有請求都使用帶有 JSON 承載的 HTTP POST。

基本請求結構

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

請求欄位

領域	類型	為必填項目	Description
`query`	字串	Yes	要執行的 GQL 查詢

回應格式

成功請求的所有回應都會使用 HTTP 200 狀態，其中包含包含執行狀態和結果的 JSON 承載。

回應結構

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

狀態物件

每個回應都包含一個具有執行資訊的狀態物件：

領域	類型	Description
`code`	字串	六個字元的狀態碼（000000 = 成功）
`description`	字串	人類可讀的狀態訊息
`diagnostics`	物件	詳細的診斷記錄
`cause`	物件	選擇性的根本原因狀態物件

狀態碼

狀態碼遵循階層式模式：

00xxxx - 圓滿成功
01xxxx - 警告成功
02xxxx - 無需數據即可成功
03xxxx - 資訊成功
04xxxx 和更高版本 - 錯誤和異常狀況

如需詳細資訊，請參閱 GQL 狀態碼參考。

診斷記錄

診斷記錄可以包含其他索引鍵值組，以進一步詳細說明狀態物件。以底線_（）開頭的鍵是圖形特有的。 GQL 標準規定了所有其他金鑰。

備註

圖中特定鍵的診斷記錄值為 JSON 編碼的 GQL 值。請參閱值類型和編碼。

原因

當已知基本原因時，狀態物件會包含選擇性 cause 欄位。

其他狀態物件

部分結果可以在（選用） additionalStatuses 欄位中報告其他狀態物件作為清單。

如果是這樣，則主要狀態物件一律會確定為 GQL 標準規定的最關鍵狀態物件（例如例外狀況）。

結果類型

結果會使用具有欄位的 kind 區別聯集模式：

表格結果

對於傳回表格式資料的查詢：

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

省略的結果

對於不傳回資料的作業（例如，目錄和/或資料更新）：

{
  "kind": "NOTHING"
}

值類型和編碼

API 使用豐富的類型系統來表示具有精確語意的 GQL 值。 GQL 值的 JSON 格式遵循區分聯合模式。

備註

表格結果的 JSON 格式透過分離gqlTypevalue來實現區分聯合模式，並實現更緊湊的表示。請參閱表格序列化最佳化。

價值結構

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

基本類型

GQL 類型	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	原生 JSON 布林值
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	UTF-8 字串

數值類型

整數類型

GQL 類型	範圍	JSON 序列化	Example
`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 序列化	Example
`FLOAT64`	IEEE 754 二進位制64	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 類型	格式	Example
`ZONED DATETIME`	YYYY-MM-DDTHH：MM：SS[.ffffff]±HH：MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

圖形元素參考類型

GQL 類型	Description	Example
`NODE`	圖形節點參考	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	圖形邊緣參考	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

複雜類型

複式類型是由其他 GQL 值所組成。

Lists

清單包含具有一致元素類型的可 Null 值陣列：

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

特殊清單類型：

LIST<ANY> - 混合類型（每個元素都包含完整類型資訊）
LIST<NULL> - 只允許空值
LIST<NOTHING> - 一律空陣列

Paths

路徑會編碼為圖形元素參考值的清單。

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

請參閱表格序列化最佳化。

表格序列化最佳化

針對表格結果，值序列化會根據資料行類型資訊進行最佳化：

已知類型 - 只有原始值會序列化
ANY columns - 具有類型鑑別器的完整值物件

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

錯誤處理

傳輸錯誤

網路和 HTTP 傳輸錯誤會導致標準 HTTP 錯誤狀態碼（4xx、5xx）。

應用程式錯誤

應用程式層級錯誤一律會傳回 HTTP 200，並在狀態物件中傳回錯誤資訊：

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

狀態檢查

若要判斷成功，請檢查狀態碼：

以 00、、 0102開03頭的代碼表示成功（可能帶有警告）
所有其他代碼都表示錯誤

使用 az rest 的完整範例

使用命令 az rest 執行查詢，以避免手動取得持有人權杖，如下所示：

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 工具從殼層執行HTTPS請求。

我們假設您有一個有效的存取權杖儲存在 shell 變數中，如下所示：

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

小提示

請參閱驗證一節，瞭解如何取得有效的持有人權杖。

執行查詢，如下所示：

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

最佳做法

使用 GQL 查詢 API 時，請遵循這些最佳實務。

錯誤處理

一律檢查狀態碼 - 請勿假設根據 HTTP 200 成功。
剖析錯誤詳細資料 - 使用診斷和原因鏈結進行偵錯。

安全性

使用 HTTPS - 切勿透過未加密的連線傳送驗證權杖。
輪替權杖 - 實作適當的權杖重新整理和到期處理。
驗證輸入 - 清理並正確逸出插入查詢中的任何使用者提供的查詢參數。

價值表示

處理大型整數值 - 如果整數無法原生表示為 JSON 數字，則整數會編碼為字串。
處理特殊浮點值 - 從查詢傳回的浮點值可以是 Infinity、 -Infinity或（ NaN 不是數字）值。
處理 Null 值 - JSON null 代表 GQL null。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-03-12

共用方式為

GQL 查詢 API 參考

概觀

主要功能

先決條件

Authentication

使用者委派的存取權

應用程式存取

API 端點

請求標頭

要求格式

基本請求結構

請求欄位

回應格式

回應結構

狀態物件

狀態碼

診斷記錄

原因

其他狀態物件

結果類型

表格結果

省略的結果

值類型和編碼

價值結構

基本類型

數值類型

整數類型

浮點類型

時間類型

圖形元素參考類型

複雜類型

Lists

Paths

表格序列化最佳化

錯誤處理

傳輸錯誤

應用程式錯誤

狀態檢查

使用 az rest 的完整範例

捲曲的完整範例

最佳做法

錯誤處理

安全性

價值表示

相關內容

意見反應

其他資源