Referência da API de Consulta GQL

Execute consultas GQL em grafos de propriedade no grafo no Microsoft Fabric usando uma API HTTP RESTful. Essa 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 de exemplos de grafos 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 retorna resultados estruturados e tipados. Ele suporta sondagem de continuidade para consultas que não terminam durante a solicitação inicial.

Características principais

Ponto de extremidade único – todas as operações usam HTTP POST em uma URL.
Baseado em JSON – os conteúdos de solicitação e resposta usam JSON com codificação avançada de valores GQL tipado.
Questionamento de continuação - Consultas de longa duração podem continuar em múltiplas requisições HTTP.
Tipo seguro – digitação forte compatível com GQL com uniões discriminadas para representação de valor.

Pré-requisitos

Você precisa de um grafo que contenha dados, incluindo nós e bordas (relações). Consulte o início rápido do grafo para criar e carregar um grafo de exemplo.
Você deve estar familiarizado com grafos de propriedade e uma compreensão básica da GQL, incluindo a estrutura de resultados e resultados da execução.
Você precisa instalar e configurar a ferramenta CLI do Azureaz para entrar em sua organização. 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, você pode obter tokens de portador usando Biblioteca do Microsoft Authenticator (MSAL) ou outros fluxos de autenticação compatíveis com Microsoft Entra.

Os tokens de portador geralmente são obtidos por meio de dois caminhos principais:

Acesso delegado pelo usuário

Você pode obter tokens de portador para chamadas de serviço delegadas pelo usuário da linha de comando por meio da ferramenta CLI do Azureaz.

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

Execute az login
Então az account get-access-token --resource https://api.fabric.microsoft.com

Isso usa a ferramenta CLI do Azureaz.

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

Acesso ao aplicativo

Você pode obter tokens de portador para aplicativos registrados em Microsoft Entra. Consulte o início rápido da API do Fabric para obter mais detalhes.

Ponto de extremidade 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 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} espaço de trabalho, você pode listar todos os workspaces 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 grafos disponíveis em um workspace usando az rest:

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

Você pode usar as opções de saída do CLI do Azure para filtrar ou formatar as respostas dessas solicitações de lista. Essas opções rodam no cliente CLI do Azure; elas não são parâmetros da API de consulta:

--query "value[?displayName=='My Workspace']" lista apenas itens com um displayName de My Workspace.
--query "value[?starts_with(displayName, 'My')]" lista apenas itens que displayName começam com My.
--query "{query}" lista apenas itens que correspondem ao JMESPath {query}fornecido. Consulte os resultados do comando 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 executar consultas por meio do ponto de extremidade de API 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 consultas.
`continuationToken`	cadeia	No	Token de `result.nextPage` quando uma consulta ainda está rodando. Envie o mesmo texto da consulta quando usar o token.

Cabeçalhos da solicitação

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

Formato de solicitação

Todas as solicitações usam HTTP POST com um conteúdo JSON.

Estrutura de solicitação básica

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

Campos de solicitação

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

Formato da resposta

Todas as respostas para solicitações bem-sucedidas usam o status HTTP 200 com conteúdo JSON contendo o status e os resultados da 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 Status

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

Campo	Tipo	Description
`code`	cadeia	Código de status público da API de cinco caracteres.
`description`	cadeia	Descrição de status legível para humanos.
`diagnostics`	objeto	Registro diagnóstico detalhado, incluindo o GQLSTATUS canônico do mecanismo de consulta quando disponível.
`cause`	objeto	Objeto opcional de status da causa subjacente.

Códigos de status

O principal status.code usa 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 suporte futuro a DDL e DML.
01000 - Condição de alerta ou informação.
02000 - Atualmente não há linhas disponíveis a partir de uma consulta que produz linhas.
42000 - Erro de sintaxe, regra de acesso ou outro erro de consulta corrigível pelo usuário.
50000 - Erro do sistema ou não classificado.

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

Registros de diagnóstico

Os registros de diagnóstico podem conter outros pares chave-valor que detalham ainda mais o objeto de status. As chaves que começam com um sublinhado (_) são específicas para o grafo. 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 mecanismo de consulta. Todo membro diagnóstico prefixado por sublinhado contém ou null um valor GQL codificado em JSON. Por exemplo, _graphaneGqlStatus usa STRING, enquanto 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 status como uma lista no campo opcional additionalStatuses .

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

Tipos de resultados

Os resultados usam um padrão de união discriminado 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 execução longa

Se uma consulta não terminar durante a requisição HTTP atual, a API retorna HTTP 200 com código 02000de status 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 da solicitação 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. Encode percentualmente exatamente uma vez de acordo com o RFC 3986 antes de usá-lo como continuationToken valor do parâmetro de consulta. Não decode, inspecione ou modifique o token.

Continue até que a resposta não conter nextPagemais . A execução da consulta pode continuar por até 20 minutos a partir da solicitação inicial. Se exceder essa duração total, a API retorna HTTP 408 com código QueryTimeoutde erro .

Resultados truncados

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

Truncamento não produz um nextPage token para as linhas omitidas. Restringir a consulta com filtros, projeções específicas ou LIMIT, e então execute novamente.

Resultados omitidos

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

{
  "kind": "NOTHING"
}

Esse 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 retornar.

O Graph reserva esse código de forma e status de resultado para suporte futuro a instruções de linguagem de definição de dados (DDL) e linguagem de manipulação de dados (DML). Instruções de consulta atuais sempre retornam 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 discriminado.

Observação

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

Estrutura de valor

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

Tipos primitivos

Tipo GQL	Example	Description
`BOOL`	`{"gqlType": "BOOL", "value": true}`	Booliano JSON nativo
`STRING`	`{"gqlType": "STRING", "value": "Hello"}`	Cadeia de caracteres UTF-8

Tipos numéricos

Tipos inteiros

Tipo GQL	Alcance	Serialização JSON	Example
`INT64`	-2⁶óduto a 2⁶óduto-1	Número ou cadeia de caracteres*	`{"gqlType": "INT64", "value": -9237}`
`UINT64`	0 a 2⁶⁴-1	Número ou cadeia de caracteres*	`{"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 cadeias de caracteres:

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

Tipos de ponto flutuante

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

Os valores de ponto flutuante dão suporte a 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 com suporte usam formatos de cadeia de caracteres ISO 8601:

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

Tipos de referência do elemento Graph

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

Tipos complexos

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

Lists

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

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

Tipos de lista especiais:

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

Paths

Os caminhos são codificados como listas de valores de referência de elemento de grafo.

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

Consulte a otimização de serialização de tabela.

Otimização de serialização de tabela

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

Tipos conhecidos – somente o valor bruto é serializado
Colunas ANY - Objeto de valor completo com tipo discriminatório

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

Status HTTP e status GQL descrevem diferentes camadas da resposta:

Status de HTTP	Meaning
200	A API processou a solicitação. Inspecione `status.code` porque o resultado pode representar sucesso, sem linhas, uma consulta ainda em andamento ou um erro de consulta corrigível pelo usuário.
408	A execução da consulta ultrapassava o tempo limite total de 20 minutos. O código de erro é `QueryTimeout`.
429	O limite de taxa de serviço foi excedido. Espere a 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	A solicitação ou serviço falhou antes de retornar um resultado de execução GQL. Inspecione a resposta de erro HTTP.

Erros de aplicativo

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

Verificação de status

Para determinar o resultado geral, verifique o público status.code. Use _graphaneGqlStatus quando sua aplicação precisar distinguir uma condição específica do mecanismo de consulta, como o excesso numérico (22003) da 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, da seguinte maneira:

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 curl

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

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

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

Dica

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

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

Práticas recomendadas

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

Tratamento de erros

Sempre verifique os códigos de status – não suponha êxito com base em HTTP 200.
Detalhes do erro de análise – Use o diagnóstico e as cadeias de causa para depuração.

Segurança

Use HTTPS – Nunca envie tokens de autenticação em conexões não criptografadas.
Girar tokens – Implementar a atualização de token e o tratamento de expiração adequados.
Validar entradas - Valide e escape corretamente de quaisquer valores fornecidos pelo usuário que sua aplicação inserir no texto da consulta.

Representação de valor

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

Comentários

Esta página foi útil?

Última atualização em 2026-09-29

Referência da API de Consulta GQL

Visão geral

Características principais

Pré-requisitos

Authentication

Acesso delegado pelo usuário

Acesso ao aplicativo

Ponto de extremidade de API

Parâmetros de consulta

Cabeçalhos da solicitação

Formato de solicitação

Estrutura de solicitação básica

Campos de solicitação

Formato da resposta

Estrutura de resposta

Objeto Status

Códigos de status

Registros de diagnóstico

Causas

Outros objetos de status

Tipos de resultados

Resultados da tabela

Consultas de execução longa

Resultados truncados

Resultados omitidos

Tipos de valor e codificação

Estrutura de valor

Tipos primitivos

Tipos numéricos

Tipos inteiros

Tipos de ponto flutuante

Tipos temporais

Tipos de referência do elemento Graph

Tipos complexos

Lists

Paths

Otimização de serialização de tabela

Tratamento de erros

Erros de transporte

Erros de aplicativo

Verificação de status

Exemplo completo com az rest

Exemplo completo com curl

Práticas recomendadas

Tratamento de erros

Segurança

Representação de valor

Conteúdo relacionado

Comentários

Recursos adicionais