GQL 查詢 API 參考

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

概觀

GQL 查詢 API 暴露了一個 REST 端點，該端點接受 GQL 查詢作為 JSON payload 並回傳結構化、型別化的結果。 它支援對未在初始請求完成的查詢進行持續輪詢。

主要功能

• 單一端點 - 所有作業都會使用HTTP POST到一個URL。
• 以 JSON 為基礎 - 請求和回應承載使用 JSON 和類型化 GQL 值的豐富編碼。
• 持續輪詢 ——長時間執行的查詢可以在多個 HTTP 請求中持續進行。
• 類型安全 - 強而有力的、與 GQL 相容的類型，具有區別的聯集以進行值表示。

先決條件

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

Authentication

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

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

Authorization: Bearer <your-access-token>

一般而言，你可以使用 Microsoft 驗證資源庫（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?beta=true

查詢 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 "value[?displayName=='My Workspace']" 僅列出 A displayName 為 的 My Workspace項目。
• --query "value[?starts_with(displayName, 'My')]" 僅列出以 displayName 開頭的 My項目。
• --query "{query}" 僅列出符合所提供 JMESPath {query}的項目。 請參閱 Query Azure CLI 命令結果以了解所支援的語法。
• -o table 用於產生表格結果。

查詢參數

請求標頭

要求格式

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

基本請求結構

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

請求欄位

回應格式

成功請求的所有回應都會使用 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": [...]
  }
}

狀態物件

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

狀態碼

主要 status.code 使用以下公開 API 類別：

• 00000 - 成功完成且至少有一行。
• 00001 - 成功完成但結果未完成。 預留給未來的 DDL 和 DML 支援。
• 01000 - 警告或資訊性狀況。
• 02000 - 目前無法從產生列查詢中取得任何資料列。
• 42000 - 語法、存取規則或其他使用者可修正的查詢錯誤。
• 50000 - 系統或非機密錯誤。

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

診斷記錄

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

原因

當已知基本原因時，狀態物件會包含選擇性 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 會回傳帶有公開狀態碼 02000、一個空資料表和 nextPage 一個標記的 HTTP 200：

{
  "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 。 在使用查詢 continuationToken 參數值前，依據 RFC 3986 精確編碼一次百分比。 不要解碼、檢查或修改該代幣。

持續直到回應不再包含 nextPage。 查詢執行可從初始請求持續長達 20 分鐘。 若超過總時長，API 會回傳帶有錯誤碼 QueryTimeout的 HTTP 408 。

截斷結果

當查詢回應的內部二進位表示超過 64 MB 時，圖會截斷其回應。 API 會回傳符合的列，並將狀態加入 additionalStatuses。 附加狀態使用公開程式碼01000，並保留 GQLS 的典範狀態01M11。_graphaneGqlStatus

截斷不會產生 nextPage 遺漏列的標記。 用篩選器、特定投影 LIMIT或 ，縮小查詢範圍，然後再執行一次。

省略的結果

回應結構可以表示一個敘述從未產生列的操作，與資料或評估結果無關。 此結果使用狀態代碼 00001：

{
  "kind": "NOTHING"
}

此遺漏結果與無列資料表不同。 空資料表是評估一個目前沒有可回傳資料列的產生列查詢的結果。

圖會保留此結果形狀與狀態碼，供未來的資料定義語言（DDL）及資料操作語言（DML）陳述式支援使用。 目前的查詢語句總是回傳表格結果。

值類型和編碼

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

價值結構

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

基本類型

數值類型

整數類型

超出 JavaScript 安全範圍（-9,007,199,254,740,991 至 9,007,199,254,740,991）的大型整數會序列化為字串：

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

浮點類型

浮點值支援 IEEE 754 特殊值：

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

時間類型

支援的時間類型會使用 ISO 8601 字串格式：

圖形元素參考類型

複雜類型

複式類型是由其他 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 - 具有類型鑑別器的完整值物件

{
  "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 程式碼 42000 ，並在診斷記錄中保留典範的 GQLSTATUS 22012 ：

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

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

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 查詢 API 時，請遵循這些最佳實務。

錯誤處理

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

安全性

• 使用 HTTPS - 切勿透過未加密的連線傳送驗證權杖。
• 輪替權杖 - 實作適當的權杖重新整理和到期處理。
• 驗證輸入—— 驗證並正確跳脫應用程式在查詢文字中插入的使用者提供的值。

價值表示

• 處理大型整數值 - 如果整數無法原生表示為 JSON 數字，則整數會編碼為字串。
• 處理特殊浮點數值——API 將正無限、負無限、非數字及負零序列化為 "Inf"、 "-Inf"、 "NaN""-0"、 和 。
• 處理 Null 值 - JSON null 代表 GQL null。

相關內容

• 圖資料模型
• GQL 語言指南
• GQL 值和值類型
• GQL 狀態碼參考