GQL 查询 API 参考

注释

此功能目前处于公开预览状态。此预览版在没有服务级别协议的情况下提供，不建议用于生产工作负荷。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版的使用条款。

使用 RESTful HTTP API 对 Microsoft Fabric 中的图形中的属性图运行 GQL 查询。此参考介绍了 HTTP 协定：请求和响应格式、身份验证、JSON 结果编码和错误处理。

重要

本文专门使用社交网络示例图形数据集。

概述

GQL 查询 API 是一个终结点（基于 HTTP 的 RPC），它接受 GQL 查询作为 JSON 有效负载并返回结构化类型化的结果。 API 是无状态的，可处理身份验证，并提供全面的错误报告。

主要功能

单终结点 - 所有作都使用 HTTP POST 到一个 URL。
基于 JSON - 请求和响应有效负载使用具有类型 GQL 值的丰富编码的 JSON。
无状态 - 请求之间不需要会话状态。
类型安全 - 具有区分联合的强 GQL 兼容类型，用于值表示形式。

先决条件

需要包含数据（包括节点和边缘）的图形（关系）。请参阅图形快速入门，以创建和加载示例图。
应熟悉属性图和对 GQL 的基本了解，包括执行结果和结果的结构。
需要安装和设置 Azure CLI 工具az以登录到组织。本文中的命令行示例假定使用与 POSIX 兼容的命令行 shell，例如 bash。

Authentication

GQL 查询 API 需要通过持有者令牌进行身份验证。

将访问令牌包含在每个请求的授权标头中：

Authorization: Bearer <your-access-token>

通常，可以使用与Microsoft Entra兼容的 Microsoft Authentication Library （MSAL）或其他身份验证流来获取持有者令牌。

持有者令牌通常通过两个主要路径获取：

用户委托的访问权限

可以通过 Azure CLI 工具az从命令行获取用户委托服务调用的持有者令牌。

通过以下命令从命令行获取用户委托调用的持有者令牌：

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"

可以使用更多参数进一步缩小查询结果的范围：

用于仅列出包含 /a0> 的项目
--query 'value[starts_with(?displayName='My')]用于仅列出以 displayName. 开头的项目My。
--query '{query}' 仅列出与提供的 JMESPath {query}匹配的项目。有关支持的语法，请参阅有关 JMESPath 的 {query}。
-o table 用于生成表结果。

注释

有关如何通过命令行 shell 通过 API 终结点执行查询，请参阅有关使用 az-rest 的部分或有关使用 curl 的部分。

请求标头

Header	价值	必选
`Content-Type`	`application/json`	是的
`Accept`	`application/json`	是的
`Authorization`	`Bearer <token>`	是的

请求格式

所有请求都将 HTTP POST 与 JSON 有效负载一起使用。

基本请求结构

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

请求字段

领域	类型	必选	Description
`query`	字符串	是的	要执行的 GQL 查询

响应格式

成功请求的所有响应都使用包含执行状态和结果的 JSON 有效负载的 HTTP 200 状态。

响应结构

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

Status 对象

每个响应都包含一个状态对象，其中包含执行信息：

领域	类型	Description
`code`	字符串	六个字符的状态代码（0000000 = success）
`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 格式通过分离 gqlType 和 value 实现更简洁的表示形式来实现歧视的联合模式。请参阅表序列化优化。

值结构

{
  "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 类型	Format	Example
`ZONED DATETIME`	YYYY-MM-DDTHH：MM：SS[.ffffff]±HH：MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Graph 元素引用类型

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> - 仅允许 null 值
LIST<NOTHING> - 始终为空数组

路径

路径编码为图形元素引用值的列表。

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

请参阅表序列化优化。

表序列化优化

对于表结果，值序列化基于列类型信息进行优化：

已知类型 - 仅序列化原始值
ANY 列 - 具有类型鉴别器的完整值对象

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

状态检查

若要确定成功，请检查状态代码：

从开始的代码指示成功（可能发出警告）
所有其他代码都指示错误

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 的完整示例

本部分中的示例使用 curl 该工具从 shell 执行 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 终结点

请求标头

请求格式

基本请求结构

请求字段

响应格式

响应结构

Status 对象

状态代码

诊断记录

原因

其他状态对象

结果类型

表结果

省略的结果

值类型和编码

值结构

基元类型

数字类型

整数类型

浮点类型

时态类型

Graph 元素引用类型

复杂类型

Lists

路径

表序列化优化

错误处理

传输错误

应用程序错误

状态检查

az rest 的完整示例

curl 的完整示例

最佳做法

错误处理

安全性

值表示形式

相关内容

反馈

其他资源