Referência da API de consulta GQL

Execute consultas GQL contra grafos de propriedades em grafos no Microsoft Fabric usando uma API HTTP RESTful. Esta referência descreve o contrato HTTP: formatos de solicitação e resposta, autenticação, codificação de resultados JSON e tratamento de erros.

Importante

Este artigo utiliza exclusivamente o conjunto de dados gráfico de exemplo de redes sociais.

Visão geral

A API de Consultas GQL expõe um endpoint REST que aceita consultas GQL como cargas úteis JSON e devolve resultados estruturados e tipados. Suporta sondagens de continuação para consultas que não terminam durante o pedido inicial.

Principais características

Ponto de extremidade único - Todas as operações usam HTTP POST para uma URL.
Baseado em JSON - As cargas úteis de solicitação e resposta usam JSON com codificação avançada de valores GQL digitados.
Sondagens de continuação - Consultas de longa duração podem continuar através de múltiplos pedidos HTTP.
Tipo seguro - Digitação forte, compatível com GQL com uniões discriminadas para representação de valor.

Pré-requisitos

Precisas de um grafo que contenha dados, incluindo nós e arestas (relações). Consulte o início rápido do gráfico para criar e carregar um gráfico de exemplo.
Você deve estar familiarizado com gráficos de propriedades e uma compreensão básica de GQL, incluindo a estrutura de resultados e resultados de execução.
Precisa de instalar e configurar a ferramenta CLI do Azureaz para iniciar sessão na sua organização. Os exemplos de linha de comando neste artigo pressupõem o uso de um shell de linha de comando compatível com POSIX, como bash.

Authentication

A API de consulta GQL requer autenticação por meio de tokens de portador.

Inclua seu token de acesso no cabeçalho Autorização de cada solicitação:

Authorization: Bearer <your-access-token>

Em geral, pode obter tokens portadores usando Biblioteca de Autenticação da Microsoft (MSAL) ou outros fluxos de autenticação compatíveis com Microsoft Entra.

Os tokens ao portador são geralmente obtidos através de dois caminhos principais:

Acesso delegado pelo usuário

Pode obter tokens portadores para chamadas de serviço delegadas pelo utilizador a partir da linha de comandos através da ferramenta CLI do Azureaz.

Obtenha um token de portador para chamadas delegadas pelo usuário na linha de comando:

Executar az login
Em seguida, az account get-access-token --resource https://api.fabric.microsoft.com

Isto utiliza a ferramenta CLI do Azureaz.

Quando você usa az rest para executar solicitações, os tokens de portador são obtidos automaticamente.

Acesso à aplicação

Pode obter tokens portadores para aplicações registadas na Microsoft Entra. Consulte o Guia de início rápido da API de malha para obter mais detalhes.

Ponto final de API

A API usa um único ponto de extremidade que aceita todas as operações de consulta:

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

A API de Consulta está em fase beta e não é recomendada para uso em produção. Defina o parâmetro de consulta necessário beta para true. O parâmetro mais antigo preview=true continua suportado para compatibilidade retroativa, mas é usado beta=true para novas integrações.

Para obter o {workspaceId} para seu espaço de trabalho, você pode listar todos os espaços de trabalho disponíveis usando az rest:

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

Para obter o {graphModelId}, você pode listar todos os gráficos disponíveis em um espaço de trabalho usando az rest:

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

Pode usar as opções de saída do CLI do Azure para filtrar ou formatar as respostas destes pedidos de lista. Estas opções correm no cliente CLI do Azure; não são parâmetros da API de Consulta:

--query "value[?displayName=='My Workspace']"lista apenas itens com um displayName .My Workspace
--query "value[?starts_with(displayName, 'My')]" lista apenas os itens que displayName começam por My.
--query "{query}" lista apenas itens que correspondem ao JMESPath {query}fornecido. Consulte os resultados dos comandos CLI do Azure para a sintaxe suportada.
-o table para produzir um resultado de tabela.

Observação

Consulte a seção sobre como usar az-rest ou a seção sobre como usar curl para saber como executar consultas por meio do endpoint da API a partir de um shell de linha de comando.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Description
`beta`	boolean	Yes	Defina para `true` usar a API beta de Consulta.
`continuationToken`	cadeia (de caracteres)	No	Token de `result.nextPage` quando uma consulta ainda está a correr. Submete o mesmo texto da consulta quando usares o token.

Cabeçalhos da requisição

Header	Valor	Obrigatório
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes
`Authorization`	`Bearer <token>`	Yes

Formato do pedido

Todas as solicitações usam HTTP POST com uma carga JSON útil.

Estrutura básica de pedidos

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

Campos de solicitação

Campo	Tipo	Obrigatório	Description
`query`	cadeia (de caracteres)	Yes	A consulta GQL a ser executada

Formato da resposta

Todas as respostas para solicitações bem-sucedidas usam o status HTTP 200 com carga JSON contendo status e resultados de execução.

Estrutura de resposta

{
  "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 de status

Cada resposta inclui um objeto de status com informações de execução:

Campo	Tipo	Description
`code`	cadeia (de caracteres)	Código de estado da API pública de cinco caracteres.
`description`	cadeia (de caracteres)	Descrição de estado legível para humanos.
`diagnostics`	objecto	Registo de diagnóstico detalhado, incluindo o estado canónico do motor de consulta GQL quando disponível.
`cause`	objecto	Objeto opcional de estado da causa subjacente.

Códigos de status

O principal status.code utiliza estas categorias públicas de API:

00000 - Conclusão bem-sucedida com pelo menos uma linha.
00001 - Conclusão bem-sucedida com resultado omitido. Reservado para futuros suportes DDL e DML.
01000 - Aviso ou condição informativa.
02000 - Atualmente, não há linhas disponíveis a partir de uma consulta que produz linhas.
42000 - Sintaxe, regra de acesso ou outro erro de consulta corrigível pelo utilizador.
50000 - Erro do sistema ou não classificado.

Para obter mais informações, consulte a referência de códigos de status GQL.

Registos de diagnóstico

Os registros de diagnóstico podem conter outros pares chave-valor que detalham ainda mais o objeto de status. As teclas que começam por sublinhado (_) são específicas de um gráfico. O padrão GQL prescreve todas as outras chaves.

Observação

O _graphaneGqlStatus diagnóstico contém o GQLSTATUS canónico de cinco caracteres reportado pelo motor de consulta. Cada membro de diagnóstico com prefixo sublinhado contém ou null um valor GQL codificado em JSON. Por exemplo, _graphaneGqlStatus usa STRING, enquanto os diagnósticos de classificação de erros usam BOOL. Consulte Tipos de valor e codificação.

Causas

Os objetos de status incluem um campo opcional cause quando uma causa subjacente é conhecida.

Outros objetos de status

Alguns resultados podem reportar outros objetos de estado como uma lista no campo opcional additionalStatuses .

O estado primário é a condição registada mais crítica. Cada estado adicional e causa aninhada tem o seu próprio código de API público e diagnóstico canónico GQLSTATUS.

Tipos de resultados

Os resultados usam um padrão de união discriminada com o kind campo:

Resultados da tabela

Para consultas que retornam dados 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 longa duração

Se uma consulta não terminar durante o pedido HTTP atual, a API devolve HTTP 200 com código 02000de estado público, uma tabela vazia e um nextPage token:

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

Solicite a conclusão enviando o mesmo corpo do pedido e adicionando o token à URL:

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

Trate nextPage como um valor opaco. Codifica-o por percentual exatamente uma vez de acordo com o RFC 3986 antes de o usar como valor do continuationToken parâmetro de consulta. Não descodifiquem, inspecionem ou modifiquem o token.

Continue até que a resposta deixe de conter nextPage. A execução da consulta pode continuar até 20 minutos a partir do pedido inicial. Se exceder essa duração total, a API devolve HTTP 408 com código QueryTimeoutde erro .

Resultados truncados

O grafo trunca uma resposta de consulta quando a sua representação binária interna excede 64 MB. A API devolve as linhas que se encaixam e adiciona um estado a additionalStatuses. O estatuto adicional utiliza código 01000 público e preserva o GQLSTATUS 01M11 canónico em _graphaneGqlStatus.

A truncação não produz um nextPage token para as linhas omitidas. Restringir a consulta com filtros, projeções específicas, ou LIMIT, e depois executá-la novamente.

Resultados omitidos

O esquema de resposta pode representar uma operação cuja instrução nunca produz linhas, independentemente dos dados ou do resultado da avaliação. Este resultado utiliza o código 00001de estado :

{
  "kind": "NOTHING"
}

Este resultado omitido difere de uma tabela sem linhas. Uma tabela vazia é o resultado da avaliação de uma consulta que produz linhas e que atualmente não tem linhas para devolver.

A Graph reserva esta forma de resultado e código de estado para futuros suportes de instruções da linguagem de definição de dados (DDL) e da linguagem de manipulação de dados (DML). As instruções de consulta atuais devolvem sempre os resultados das tabelas.

Tipos de valor e codificação

A API usa um sistema de tipo avançado para representar valores GQL com semântica precisa. O formato JSON dos valores GQL segue um padrão de união discriminada.

Observação

O formato JSON de resultados tabulares realiza o padrão de união discriminada separando gqlType e value alcançando uma representação mais compacta. Consulte Otimização de serialização de tabela.

Estrutura de valores

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

Tipos primitivos

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

Tipos numéricos

Tipos inteiros

Tipo GQL	Alcance	Serialização JSON	Example
`INT64`	-2⁶³ a 2⁶³-1	Número ou string*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 a 2⁶⁴-1	Número ou string*	`{"gqlType": "UINT64", "value": 18467}`

Grandes inteiros fora do intervalo seguro do JavaScript (-9,007,199,254,740,991 a 9,007,199,254,740,991) são serializados como strings:

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

Tipos de vírgula flutuante

Tipo GQL	Alcance	Serialização JSON	Example
`FLOAT64`	IEEE 754 binário64	Número JSON ou cadeia de caracteres	`{"gqlType": "FLOAT64", "value": 3.14}`

Os valores de vírgula flutuante suportam valores especiais IEEE 754:

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

Tipos temporais

Os tipos temporais suportados usam formatos de cadeia de caracteres 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 referência de elementos gráficos

Tipo GQL	Description	Example
`NODE`	Referência do nó do gráfico	`{"gqlType": "NODE", "value": "node-123"}`
`EDGE`	Referência da borda do gráfico	`{"gqlType": "EDGE", "value": "edge_abc#def"}`

Tipos complexos

Os tipos complexos são compostos por outros valores de GQL.

Lists

As listas contêm matrizes de valores anuláveis com tipos de elementos consistentes:

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

Tipos de listas especiais:

LIST<ANY> - Tipos mistos (cada elemento inclui informações completas do tipo)
LIST<NULL> - Apenas valores nulos permitidos
LIST<NOTHING> - Matriz sempre vazia

Paths

Os caminhos são codificados como listas de valores de referência de elementos gráficos.

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

Consulte Otimização de serialização de tabela.

Otimização de serialização de tabela

Para resultados de tabela, a serialização de valor é otimizada com base nas informações de tipo de coluna:

Tipos conhecidos - Somente o valor bruto é serializado
ANY columns - Objeto de valor completo com discriminador de tipo

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

Tratamento de erros

Erros de transporte

O estado HTTP e o estado GQL descrevem diferentes camadas da resposta:

Estado HTTP	Meaning
200	A API processou o pedido. Inspecione `status.code` porque o resultado pode representar sucesso, sem linhas, uma consulta ainda em curso ou um erro de consulta corrigível pelo utilizador.
408	A execução da consulta ultrapassou o tempo limite total de 20 minutos. O código de erro é `QueryTimeout`.
429	O limite de tarifa de serviço foi ultrapassado. Espere pela duração no `Retry-After` cabeçalho antes de tentar novamente.
499	O interlocutor cancelou o pedido. O código de erro é `ClientCancelled`.
Outros 4xx ou 5xx	O pedido ou serviço falhou antes de devolver um resultado de execução GQL. Inspeciona a resposta de erro HTTP.

Erros de aplicação

Um erro ao nível da aplicação pode devolver HTTP 200 com informação de erro no objeto de estado. Por exemplo, a divisão por zero usa o código 42000 público da API e preserva o GQLSTATUS 22012 canónico no registo 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
      }
    }
  }
}

Verificação de status

Para determinar o resultado geral, verifique o público status.code. Use _graphaneGqlStatus quando a sua aplicação precisar de distinguir uma condição específica do motor de consulta, como o excesso numérico (22003) de divisão por zero (22012).

Exemplo completo com az rest

Execute uma consulta usando o az rest comando para evitar ter que obter tokens de portador manualmente, assim:

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

Exemplo completo com ondulação

O exemplo nesta seção usa a curl ferramenta para executar solicitações HTTPS do shell.

Supomos que você tenha um token de acesso válido armazenado em uma variável shell, da seguinte forma:

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

Sugestão

Consulte a seção sobre autenticação para saber como obter um token de portador válido.

Execute uma consulta assim:

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

Melhores práticas

Siga estas práticas recomendadas ao usar a API de consulta GQL.

Tratamento de erros

Verifique sempre os códigos de status - Não assuma o sucesso com base no HTTP 200.
Analisar detalhes do erro - Use diagnósticos e cadeias de causas para depuração.

Segurança

Usar HTTPS - Nunca envie tokens de autenticação por conexões não criptografadas.
Girar tokens - Implemente o tratamento adequado de atualização e expiração de tokens.
Validar entradas - Validar e eliminar corretamente quaisquer valores fornecidos pelo utilizador que a sua aplicação insera no texto da consulta.

Representação de valor

Manipular valores inteiros grandes - Os inteiros são codificados como cadeias de caracteres se não puderem ser representados como números JSON nativamente.
Tratar valores especiais de ponto flutuante - A API serializa infinito positivo, infinito negativo, não-um-número e menos zero como "Inf", "-Inf", "NaN", e "-0".
Manipular valores nulos - JSON null representa GQL null.

Comentários

Esta página foi útil?

Last updated on 2026-09-29

Referência da API de consulta GQL

Visão geral

Principais características

Pré-requisitos

Authentication

Acesso delegado pelo usuário

Acesso à aplicação

Ponto final de API

Parâmetros de consulta

Cabeçalhos da requisição

Formato do pedido

Estrutura básica de pedidos

Campos de solicitação

Formato da resposta

Estrutura de resposta

Objeto de status

Códigos de status

Registos de diagnóstico

Causas

Outros objetos de status

Tipos de resultados

Resultados da tabela

Consultas de longa duração

Resultados truncados

Resultados omitidos

Tipos de valor e codificação

Estrutura de valores

Tipos primitivos

Tipos numéricos

Tipos inteiros

Tipos de vírgula flutuante

Tipos temporais

Tipos de referência de elementos gráficos

Tipos complexos

Lists

Paths

Otimização de serialização de tabela

Tratamento de erros

Erros de transporte

Erros de aplicação

Verificação de status

Exemplo completo com az rest

Exemplo completo com ondulação

Melhores práticas

Tratamento de erros

Segurança

Representação de valor

Conteúdo relacionado

Comentários

Recursos adicionais