Referência da API de Consulta GQL

Observação

Esse recurso está atualmente em versão prévia pública. Essa versão prévia é oferecida sem um SLA e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Supplemental Terms of Use for Microsoft Azure Previews.

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 Consulta GQL é um único ponto de extremidade (RPC sobre HTTP) que aceita consultas GQL como cargas JSON e retorna resultados estruturados e tipados. A API é sem estado, manipula a autenticação e fornece relatórios de erros abrangentes.

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.
Sem estado – nenhum estado de sessão necessário entre solicitações.
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 Azure CLIaz 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 Microsoft Authentication Library (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 Azure CLIaz.

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 Azure CLIaz.

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

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 {graphId}, 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 mais parâmetros para restringir ainda mais os resultados da consulta:

--query 'value[?displayName=='My Workspace'] para listar apenas itens com um displayName de My Workspace.
--query 'value[starts_with(?displayName='My')] para listar apenas itens cujos displayName inícios são My.
--query '{query}' para listar apenas os itens que correspondem ao JMESPath {query}fornecido. Consulte a documentação Azure CLI no JMESPath sobre a sintaxe com suporte para {query}.
-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.

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": "",
      "OPERATION_CODE": "0",
      "CURRENT_SCHEMA": "/"
    }
  },
  "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 de seis caracteres (000000 = êxito)
`description`	cadeia	Mensagem de status legível por humanos
`diagnostics`	objeto	Registros de diagnóstico detalhados
`cause`	objeto	Objeto de status de causa subjacente opcional

Códigos de status

Os códigos de status seguem um padrão hierárquico:

00xxxx - Sucesso total
01xxxx - Êxito com avisos
02xxxx - Êxito sem dados
03xxxx - Êxito com informações
04xxxx e superior - Erros e condições de exceção

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

Os valores no registro de diagnóstico de chaves específicas do grafo são valores GQL codificados em JSON. 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 relatar outros objetos de status como uma lista no campo (opcional). additionalStatuses

Nesse caso, o objeto de status primário é sempre determinado como o objeto de status mais crítico (como uma condição de exceção), conforme prescrito pelo padrão GQL.

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

Resultados omitidos

Para operações que não retornam dados (por exemplo, catálogo e/ou atualizações de dados):

{
  "kind": "NOTHING"
}

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

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

Tratamento de erros

Erros de transporte

Erros de transporte de rede e HTTP resultam em códigos de status de erro HTTP padrão (4xx, 5xx).

Erros de aplicativo

Os erros no nível do aplicativo sempre retornam HTTP 200 com informações de erro no objeto de status:

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

Verificação de status

Para determinar o êxito, verifique o código de status:

Códigos que começam com 00, 01, , 0203indicam êxito (com possíveis avisos)
Todos os outros códigos indicam erros

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

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

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 – Sanitize e escape corretamente todos os parâmetros de consulta fornecidos pelo usuário injetados na 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.
Manipular valores especiais de ponto flutuante – os valores de ponto flutuante retornados de consultas podem ser Infinityvalores , -Infinityou NaN (não um número).
Manipular valores nulos – nulo JSON representa GQL nulo.

Comentários

Esta página foi útil?

Last updated on 2026-03-12

Compartilhar via

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

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

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