Referencia de la API de consulta de GQL

Ejecute consultas GQL en gráficos de propiedades en Microsoft Fabric mediante una API HTTP RESTful. En esta referencia se describe el contrato HTTP: formatos de solicitud y respuesta, autenticación, codificación de resultados JSON y control de errores.

Importante

Este artículo utiliza exclusivamente el conjunto de datos de ejemplo de grafos de redes sociales.

Información general

La API de consultas GQL expone un punto final REST que acepta consultas GQL como cargas útiles JSON y devuelve resultados estructurados y tipados. Soporta sondeos de continuación para consultas que no terminan durante la solicitud inicial.

Características clave

Punto de conexión único : todas las operaciones usan HTTP POST en una dirección URL.
Basado en JSON : las cargas de solicitud y respuesta usan JSON con codificación enriquecida de valores GQL con tipo.
Encuestas de continuación - Las consultas de larga duración pueden continuar a través de múltiples solicitudes HTTP.
Tipo seguro : escritura fuerte compatible con GQL con uniones discriminadas para la representación de valores.

Prerrequisitos

Necesita un gráfico que contenga datos, incluidos nodos y bordes (relaciones). Consulte el inicio rápido del grafo para crear y cargar un gráfico de ejemplo.
Debe estar familiarizado con los gráficos de propiedades y un conocimiento básico de GQL, incluida la estructura de los resultados y los resultados de la ejecución.
Debe instalar y configurar la herramienta CLI de Azure herramienta az para iniciar sesión en su organización. En los ejemplos de línea de comandos de este artículo se presupone el uso de un shell de línea de comandos compatible con POSIX, como Bash.

Autenticación

La API de consulta de GQL requiere autenticación a través de tokens de portador.

Incluya el token de acceso en el encabezado autorización de cada solicitud:

Authorization: Bearer <your-access-token>

En general, puede obtener tokens de portador mediante Biblioteca de autenticación de Microsoft (MSAL) u otros flujos de autenticación compatibles con Microsoft Entra.

Los tokens de portador se obtienen normalmente a través de dos rutas principales:

Acceso delegado de usuario

Puede obtener tokens de portador para las llamadas de servicio delegadas por el usuario desde la línea de comandos a través de la herramienta CLI de Azureaz.

Obtenga un token de portador para las llamadas delegadas por el usuario desde la línea de comandos mediante:

Ejecute az login:
Y luego az account get-access-token --resource https://api.fabric.microsoft.com

Usa la herramienta CLI de Azureaz.

Cuando se usa az rest para realizar solicitudes, los tokens de portador se obtienen automáticamente.

Acceso a la aplicación

Puede obtener tokens de portador para las aplicaciones registradas en Microsoft Entra. Consulte el inicio rápido de Fabric API para obtener más información.

Punto de conexión de la API

La API usa un único punto de conexión que acepta todas las operaciones de consulta:

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

La API de consulta está en beta y no se recomienda para uso en producción. Establece el parámetro de consulta requerido beta en true. El parámetro antiguo preview=true sigue siendo compatible con versiones anteriores, pero se utiliza beta=true para nuevas integraciones.

Para obtener el para el {workspaceId} área de trabajo, puede enumerar todas las áreas de trabajo disponibles mediante az rest:

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

Para obtener , {graphModelId}puede enumerar todos los gráficos disponibles en un área de trabajo mediante az rest:

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

Puedes usar las opciones de salida de CLI de Azure para filtrar o formatear las respuestas de estas solicitudes de lista. Estas opciones se ejecutan en el cliente de CLI de Azure; no son parámetros de API de consulta:

--query "value[?displayName=='My Workspace']" Solo lista los elementos con un displayName de My Workspace.
--query "value[?starts_with(displayName, 'My')]" solo lista los elementos que displayName comienzan con My.
--query "{query}" solo lista los elementos que coinciden con el JMESPath {query}proporcionado. Consulta los resultados de los comandos de CLI de Azure para la sintaxis soportada.
-o table para generar un resultado de tabla.

Nota:

Consulte la sección sobre el uso de az-rest o la sección sobre el uso de curl para obtener información sobre cómo ejecutar consultas a través del punto de conexión de API desde un shell de línea de comandos.

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Description
`beta`	boolean	Sí	Configura para `true` usar la API beta de consultas.
`continuationToken`	cuerda / cadena	No	Token de `result.nextPage` cuando una consulta sigue en ejecución. Envía el mismo texto de consulta cuando uses el token.

Encabezados de solicitud

Header	Importancia	Obligatorio
`Content-Type`	`application/json`	Sí
`Accept`	`application/json`	Sí
`Authorization`	`Bearer <token>`	Sí

Formato de solicitud

Todas las solicitudes usan HTTP POST con una carga JSON.

Estructura de solicitud básica

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

Campos de solicitud

Campo	Tipo	Obligatorio	Description
`query`	cuerda / cadena	Sí	Consulta GQL que se va a ejecutar

Formato de respuesta

Todas las respuestas para solicitudes correctas usan el estado HTTP 200 con carga JSON que contiene el estado de ejecución y los resultados.

Estructura de respuesta

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

Objeto Status

Cada respuesta incluye un objeto de estado con información de ejecución:

Campo	Tipo	Description
`code`	cuerda / cadena	Código de estado de la API pública de cinco caracteres.
`description`	cuerda / cadena	Descripción de estado legible para humanos.
`diagnostics`	objeto	Registro diagnóstico detallado, incluyendo el estado canónico del motor de consulta GQL cuando esté disponible.
`cause`	objeto	Objeto opcional de estado de causa subyacente.

Códigos de estado

El uso principal status.code de estas categorías públicas de API:

00000 - Completar con éxito al menos una fila.
00001 - Finalización exitosa con resultado omitido. Reservado para futuros soportes DDL y DML.
01000 - Advertencia o condición informativa.
02000 - Actualmente no hay filas disponibles desde una consulta que produzca filas.
42000 - Error de sintaxis, regla de acceso u otro error de consulta corregible por el usuario.
50000 - Error del sistema o no clasificado.

Para obtener más información, consulte la referencia de códigos de estado de GQL.

Registros de diagnóstico

Los registros de diagnóstico pueden contener otros pares clave-valor que detallan aún más el objeto de estado. Las claves que comienzan con un carácter de subrayado (_) son específicas del grafo. El estándar GQL prescribe todas las demás claves.

Nota:

El _graphaneGqlStatus diagnóstico contiene el GQLSTATUS canónico de cinco caracteres reportado por el motor de consultas. Cada miembro diagnóstico con prefijo subestimado contiene un null valor GQL codificado en JSON o un otro. Por ejemplo, _graphaneGqlStatus usa STRING, mientras que los diagnósticos de clasificación de errores usan BOOL. Consulte Tipos de valor y codificación.

Causas

Los objetos de estado incluyen un campo opcional cause cuando se conoce una causa subyacente.

Otros objetos de estado

Algunos resultados pueden informar otros objetos de estado como una lista en el campo opcional additionalStatuses .

El estado primario es la condición más crítica registrada. Cada estado adicional y causa anidada tiene su propio código de API público y diagnóstico canónico de GQLSTATUS.

Tipos de resultados

Los resultados usan un patrón de unión discriminado con el kind campo :

Resultados de la tabla

Para las consultas que devuelven datos tabulares:

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

Consultas de ejecución prolongada

Si una consulta no termina durante la solicitud HTTP actual, la API devuelve HTTP 200 con código 02000de estado público, una tabla vacía y un nextPage token:

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

Solicita la finalización enviando el mismo cuerpo de la solicitud y añadiendo el token a la URL:

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

Trátalo nextPage como un valor opaco. Códalo-en por ciento exactamente una vez según el RFC 3986 antes de usarlo como valor del continuationToken parámetro de consulta. No decodifiques, inspecciones ni modifiques el token.

Continúa hasta que la respuesta deje de contener nextPage. La ejecución de la consulta puede continuar hasta 20 minutos desde la solicitud inicial. Si supera esa duración total, la API devuelve HTTP 408 con código QueryTimeoutde error .

Resultados truncados

Graph trunca una respuesta de consulta cuando su representación binaria interna supera los 64 MB. La API devuelve las filas que encajan y añade un estado a additionalStatuses. El estado adicional utiliza código 01000 público y preserva el GQLSTATUS 01M11 canónico en _graphaneGqlStatus.

El truncamiento no produce un nextPage token para las filas omitidas. Filtra la consulta con filtros, proyecciones específicas o LIMIT, y luego ejecuta de nuevo.

Resultados omitidos

El esquema de respuesta puede representar una operación cuya instrucción nunca produce filas, independientemente del resultado de los datos o de la evaluación. Este resultado utiliza código 00001de estado :

{
  "kind": "NOTHING"
}

Este resultado omitido difiere de una tabla sin filas. Una tabla vacía es el resultado de evaluar una consulta que produce filas y que actualmente no tiene filas que devolver.

Graph reserva este código de forma de resultado y estado para futuros soportes con el lenguaje de definición de datos (DDL) y el lenguaje de manipulación de datos (DML). Las sentencias de consulta actuales siempre devolven resultados de tablas.

Tipos de valor y codificación

La API usa un sistema de tipos enriquecido para representar valores GQL con semántica precisa. El formato JSON de los valores GQL sigue un patrón de unión discriminado.

Nota:

El formato JSON de los resultados tabulares se da cuenta del patrón de unión discriminado separando gqlType y value logrando una representación más compacta. Consulte Optimización de la serialización de tablas.

Estructura de valores

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

Tipos primitivos

Tipo GQL	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Boolean JSON nativo
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	Cadena UTF-8

Tipos numéricos

Tipos enteros

Tipo GQL	Intervalo	Serialización JSON	Example
`INT64`	-2⁶³ a 2⁶³-1	Número o cadena*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	De 0 a 2⁶⁴-1	Número o cadena*	`{"gqlType": "UINT64", "value": 18467}`

Los enteros grandes fuera del intervalo seguro de JavaScript (-9.007.199.254.740.991 a 9.007.199.254.740.991) se serializan como cadenas:

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

Tipos de punto flotante

Tipo GQL	Intervalo	Serialización JSON	Example
`FLOAT64`	IEEE 754 binary64	Número o cadena JSON	`{"gqlType": "FLOAT64", "value": 3.14}`

Los valores de punto flotante admiten valores especiales IEEE 754:

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

Tipos temporales

Los tipos temporales admitidos usan formatos de cadena ISO 8601:

Tipo GQL	Formato	Example
`ZONED DATETIME`	AAAA-MM-DDTHH:MM:SS[.ffffff]±HH:MM	`{"gqlType": "ZONED DATETIME", "value": "2023-12-25T14:30:00+02:00"}`

Tipos de referencia del elemento Graph

Tipo GQL	Description	Example
`NODE`	Referencia de nodo de grafo	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Referencia de borde del grafo	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Tipos complejos

Los tipos complejos se componen de otros valores GQL.

Lists

Las listas contienen matrices de valores que aceptan valores NULL con tipos de elementos coherentes:

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

Tipos de lista especiales:

LIST<ANY> - Tipos mixtos (cada elemento incluye información de tipo completo)
LIST<NULL> - Solo se permiten valores NULL.
LIST<NOTHING> - Matriz siempre vacía

Paths

Las rutas de acceso se codifican como listas de valores de referencia de elementos de grafos.

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

Consulte Optimización de la serialización de tablas.

Optimización de serialización de tablas

Para los resultados de la tabla, la serialización de valores se optimiza en función de la información de tipo de columna:

Tipos conocidos : solo se serializa el valor sin procesar.
COLUMNAS ANY : objeto de valor completo con discriminador de tipos

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

Control de errores

Errores de transporte

El estado HTTP y el estado GQL describen diferentes capas de la respuesta:

Estado HTTP	Meaning
200	La API procesó la solicitud. Inspecciona `status.code` porque el resultado puede representar éxito, sin filas, una consulta aún en curso o un error de consulta corregible por el usuario.
408	La ejecución de la consulta superaba el tiempo límite total de 20 minutos. El código de error es `QueryTimeout`.
429	Se superó el límite de frecuencia de servicio. Espera a que termine la duración del `Retry-After` encabezado antes de volver a intentarlo.
499	La persona que llamó canceló la solicitud. El código de error es `ClientCancelled`.
Otros 4xx o 5xx	La solicitud o servicio falló antes de devolver un resultado de ejecución GQL. Inspecciona la respuesta al error HTTP.

Errores de aplicación

Un error a nivel de aplicación puede devolver HTTP 200 con la información de error en el objeto de estado. Por ejemplo, la división por cero utiliza el código 42000 público de la API y preserva el estado 22012 canónico GQL en el registro diagnóstico:

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

Comprobación de estado

Para determinar el resultado general, consulta el público status.code. Úsalo _graphaneGqlStatus cuando tu aplicación necesita distinguir una condición específica del motor de consulta, como el desbordamiento numérico (22003) de división por cero (22012).

Ejemplo completo con az rest

Ejecute una consulta mediante el az rest comando para evitar tener que obtener tokens de portador manualmente, de la siguiente manera:

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

Ejemplo completo con curl

En el ejemplo de esta sección se usa la curl herramienta para realizar solicitudes HTTPS desde el shell.

Se supone que tiene un token de acceso válido almacenado en una variable de shell, de la siguiente manera:

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

Sugerencia

Consulte la sección sobre la autenticación para obtener un token de portador válido.

Ejecute una consulta como esta:

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

procedimientos recomendados

Siga estos procedimientos recomendados al usar la API de consulta de GQL.

Control de errores

Comprobar siempre los códigos de estado : no suponga que se ha realizado correctamente en función de HTTP 200.
Análisis de los detalles del error : use diagnósticos y cadenas de causa para la depuración.

Security

Usar HTTPS : no enviar nunca tokens de autenticación a través de conexiones sin cifrar.
Rotación de tokens: implemente el control de expiración y actualización de tokens adecuados.
Validar entradas - Validar y eliminar correctamente cualquier valor proporcionado por el usuario que tu aplicación inserte en el texto de la consulta.

Representación de valor

Controlar valores enteros grandes : los enteros se codifican como cadenas si no se pueden representar como números JSON de forma nativa.
Manejar valores especiales de coma flotante - La API serializa infinito positivo, infinito negativo, no-a-número y -cero como "Inf", "-Inf", "NaN", y "-0".
Controlar valores NULL : JSON null representa GQL null.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-09-29

Referencia de la API de consulta de GQL

Información general

Características clave

Prerrequisitos

Autenticación

Acceso delegado de usuario

Acceso a la aplicación

Punto de conexión de la API

Parámetros de consulta

Encabezados de solicitud

Formato de solicitud

Estructura de solicitud básica

Campos de solicitud

Formato de respuesta

Estructura de respuesta

Objeto Status

Códigos de estado

Registros de diagnóstico

Causas

Otros objetos de estado

Tipos de resultados

Resultados de la tabla

Consultas de ejecución prolongada

Resultados truncados

Resultados omitidos

Tipos de valor y codificación

Estructura de valores

Tipos primitivos

Tipos numéricos

Tipos enteros

Tipos de punto flotante

Tipos temporales

Tipos de referencia del elemento Graph

Tipos complejos

Lists

Paths

Optimización de serialización de tablas

Control de errores

Errores de transporte

Errores de aplicación

Comprobación de estado

Ejemplo completo con az rest

Ejemplo completo con curl

procedimientos recomendados

Control de errores

Security

Representación de valor

Contenido relacionado

Comentarios

Recursos adicionales