Referência da API de consulta GQL

Observação

Esta funcionalidade está atualmente em pré-visualização pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

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

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.
Apátrida - Nenhum estado de sessão é necessário entre as solicitações.
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 Azure CLIaz 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 Microsoft Authentication Library (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 Azure CLIaz.

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

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

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

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 cujo displayName início com My.
--query '{query}' para listar apenas itens que correspondem ao JMESPath {query}fornecido. Consulte a documentação Azure CLI sobre JMESPath relativa à sintaxe suportada 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 saber como executar consultas por meio do endpoint da API a partir de um shell de linha de comando.

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

Códigos de status

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

00xxxx - Sucesso completo
01xxxx - Sucesso com avisos
02xxxx - Sucesso sem dados
03xxxx - Sucesso com a informação
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.

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

Os valores no registo diagnóstico de chaves específicas de um 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

Em caso afirmativo, 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 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": "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, atualizações de catálogo e/ou 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 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

{
  "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 aplicação

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 sucesso, verifique o código de status:

Códigos que começam com 00, 01, 02, indicam 03 sucesso (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, assim:

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

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 - Limpe e escape adequadamente de quaisquer parâmetros de consulta fornecidos pelo usuário injetados na 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.
Manipular valores de ponto flutuante especiais - Os valores de ponto flutuante retornados de consultas podem ser Infinity, -Infinityou NaN (não um número) valores.
Manipular valores nulos - JSON null representa GQL null.

Comentários

Esta página foi útil?

Last updated on 2026-03-12

Partilhar via

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

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

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