Referencia de la API de consulta de GQL

Nota:

Esta característica actualmente está en su versión preliminar pública. Esta versión preliminar se ofrece sin un contrato de nivel de servicio y no es aconsejable usarla para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

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 consulta de GQL es un único punto de conexión (RPC a través de HTTP) que acepta consultas GQL como cargas JSON y devuelve resultados estructurados y tipados. La API no tiene estado, controla la autenticación y proporciona informes completos de errores.

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.
Sin estado: no se requiere ningún estado de sesión entre las solicitudes.
Tipo seguro : escritura fuerte compatible con GQL con uniones discriminadas para la representación de valores.

Prerrequisitos

Necesita un gráfico en Microsoft Fabric 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 de la 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 la 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 de la az ,

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

Esto usa la herramienta de la az .

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?preview=true

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

Puede usar más parámetros para restringir aún más los resultados de la consulta:

--query 'value[?displayName=='My Workspace'] para enumerar solo elementos con un displayName de My Workspace.
--query 'value[starts_with(?displayName='My')] para enumerar solo los elementos cuyo displayName inicio es My.
--query '{query}' para enumerar solo los elementos que coinciden con el JMESPath {query}proporcionado. Consulte la documentación de la CLI de Azure sobre JMESPath con respecto a la sintaxis admitida para {query}.
-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.

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": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "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 seis caracteres (000000 = correcto)
`description`	cuerda / cadena	Mensaje de estado legible
`diagnostics`	objeto	Registros de diagnóstico detallados
`cause`	objeto	Objeto de estado de causa subyacente opcional

Códigos de estado

Los códigos de estado siguen un patrón jerárquico:

00xxxx - Finalización correcta
01xxxx - Correcto con advertencias
02xxxx - Correcto sin datos
03xxxx - Correcto con información
04xxxx y versiones posteriores: errores y condiciones de excepción

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 por un carácter de subrayado (_) son específicas del grafo de Microsoft Fabric. El estándar GQL prescribe todas las demás claves.

Nota:

Los valores del registro de diagnóstico de claves específicas del grafo de Microsoft Fabric son valores GQL codificados en JSON. 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 notificar otros objetos de estado como una lista en el campo (opcional). additionalStatuses

Si es así, el objeto de estado principal siempre se determina como el objeto de estado más crítico (por ejemplo, una condición de excepción) según lo indicado por el estándar GQL.

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": "INT32",
      "jsonType": "number"
    }
  ],
  "isOrdered": true,
  "isDistinct": false,
  "data": [
    {
      "name": "Alice",
      "age": 30
    },
    {
      "name": "Bob",
      "age": 25
    }
  ]
}

Resultados omitidos

Para las operaciones que no devuelven datos (por ejemplo, actualizaciones de catálogo o datos):

{
  "kind": "NOTHING"
}

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

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

Control de errores

Errores de transporte

Los errores de transporte HTTP y de red producen códigos de estado de error HTTP estándar (4xx, 5xx).

Errores de aplicación

Los errores de nivel de aplicación siempre devuelven HTTP 200 con información de error en el objeto de estado:

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

Comprobación de estado

Para determinar si se ha realizado correctamente, compruebe el código de estado:

Códigos que comienzan por 00, 01, 02, indican 03 que se ha realizado correctamente (con posibles advertencias)
Todos los demás códigos indican errores

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

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

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 : sane y escape correctamente los parámetros de consulta proporcionados por el usuario insertados en 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.
Controlar valores de punto flotante especiales : los valores de punto flotante devueltos de las consultas pueden ser Infinityvalores , -Infinityo NaN (no un número).
Controlar valores NULL : JSON null representa GQL null.

Ohar-bidaltzea

Lagungarria izan al da orrialde hau?

Last updated on 2025-11-18

Partekatu bidez

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

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

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

Ohar-bidaltzea

Baliabide gehigarriak