Partilhar via

API de malha para editor GraphQL

A API de malha para GraphQL fornece um ambiente de desenvolvimento gráfico no navegador GraphQL, que permite um playground interativo para compor, testar e ver os resultados ao vivo de suas consultas e mutações do GraphQL.

Quem utiliza o editor GraphQL

O editor GraphQL é essencial para:

  • Desenvolvedores de aplicações a criar protótipos e testar queries nos dados do Fabric antes de implementá-las nas aplicações
  • Engenheiros de dados a explorar estruturas de dados em lagos e armazéns e a validar designs de esquemas GraphQL
  • Contribuintes do Fabric Workspace a testar permissões de acesso a dados e a resolver problemas de consultas
  • Desenvolvedores de BI aprendendo a estrutura da API e a criar padrões de acesso a dados para aplicações personalizadas
  • Equipas de desenvolvimento a colaborar no desenvolvimento de consultas e na resolução de problemas de acesso a dados nos espaços de trabalho do Fabric

Use o editor sempre que precisar de desenvolver, testar ou depurar consultas GraphQL interativamente contra as suas fontes de dados Fabric.

Comece a usar o editor GraphQL

Siga estes passos para começar a usar o editor GraphQL:

  1. Abra o item da API GraphQL - Navegue até ao seu espaço de trabalho no Fabric e abra a API para o item GraphQL.

  2. Acede ao editor - Selecione Consulta no canto inferior esquerdo do ecrã do portal.

    Captura de tela mostrando onde a opção Consulta aparece no canto inferior esquerdo da tela Malha.

  3. Escreva a sua consulta - Escreva as suas consultas GraphQL diretamente no separador de Consultas . Use o Intellisense com atalhos de teclado:

    • Windows: CTRL + Espaço
    • macOS: Comando + Espaço

    Captura de tela da tela do editor de API, que mostra uma guia Consulta dividida em painéis Executar, Variáveis de consulta e Resultados.

  4. Executar a consulta - Selecione Executar para executar a consulta e recuperar dados da sua fonte de dados.

Gerar código

O editor de API gera automaticamente código padrão em Python ou Node.js que reflete a consulta ou mutação do GraphQL que está a testar no editor. À medida que prototipas e refinas as tuas consultas, o código gerado atualiza-se em conformidade. Quando estiver satisfeito com os resultados, pode visualizar e copiar o código gerado para executar localmente para fins de teste ou reutilizá-lo no seu processo de desenvolvimento de aplicações.

Important

O código gerado usa credenciais interativas do navegador e deve ser usado apenas para fins de teste. Na produção, sempre cadastre um aplicativo no Microsoft Entra e utilize os escopos e escopos apropriados client_id . Você pode encontrar um exemplo de ponta a ponta com código de exemplo em Connect Applications.

Para começar:

  1. Escreva uma consulta - Introduza a seguinte consulta de exemplo (ou a sua própria) no editor de Consultas:

    query {
  addresses(first: 5) {
     items {
        AddressID
        City
        StateProvince
        CountryRegion
     }  
  }
}

  2. Executa a consulta - Seleciona Executar para executar a consulta e verifica se funciona corretamente no editor antes de prosseguir.

  3. Gerar código - Selecione o botão Gerar código e depois selecione a sua linguagem de programação preferida (Python ou JavaScript/Node.JS):

    Captura de ecrã do editor de API que mostra o menu suspenso para selecionar a linguagem de programação do código gerado.

  4. Em seguida, você pode copiar o código gerado e salvá-lo como um arquivo em uma pasta local. Dependendo da língua escolhida, siga estes passos rápidos para testar localmente:

Python

  1. Crie um ficheiro com nome editor.py e cole o código gerado a partir da consulta de exemplo acima.

  2. Crie um ambiente virtual executando o comando python -m venv .venv.

  3. Ative o venv executando .venv\Scripts\activate ou source .venv/bin/activate.

  4. Instale a dependência necessária executando pip install azure-identityo .

  5. Execute o código com python editor.py.

  6. É solicitado que inicie sessão através de uma janela do navegador para autenticar o pedido.

  7. A resposta da API é impressa na consola.

    {
	"data": {
		"addresses": {
			"items": [
				{
					"AddressID": 9,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 11,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 25,
					"City": "Dallas",
					"StateProvince": "Texas",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 28,
					"City": "Phoenix",
					"StateProvince": "Arizona",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 32,
					"City": "Montreal",
					"StateProvince": "Quebec",
					"CountryRegion": "Canada"
				}
			]
		}
	}
}

Node.JS

  1. Crie um ficheiro com nome editor.js e cole o código gerado a partir da consulta de exemplo acima.

  2. Na mesma pasta que editor.js, crie um package.json ficheiro com o seguinte conteúdo:

    {
  "type": "module",
  "dependencies": {}
}

  3. InstalaNode.js na tua máquina de desenvolvimento (inclui o npm)

  4. Execute npm install @azure/identity ou um comando semelhante no gerenciador de pacotes escolhido para instalar a versão mais recente da biblioteca de identidades.

  5. Execute node editor.js para executar o código.

  6. É solicitado que inicie sessão através de uma janela do navegador para autenticar o pedido.

  7. A resposta da API é impressa na consola.

    {
	"data": {
		"addresses": {
			"items": [
				{
					"AddressID": 9,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 11,
					"City": "Bothell",
					"StateProvince": "Washington",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 25,
					"City": "Dallas",
					"StateProvince": "Texas",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 28,
					"City": "Phoenix",
					"StateProvince": "Arizona",
					"CountryRegion": "United States"
				},
				{
					"AddressID": 32,
					"City": "Montreal",
					"StateProvince": "Quebec",
					"CountryRegion": "Canada"
				}
			]
		}
	}
}

Desenvolvimento de consultas e mutações

Os exemplos seguintes demonstram a sintaxe de consultas e mutações do GraphQL usando os dados de exemplo do AdventureWorks. Estes exemplos assumem que está a trabalhar com um Fabric Data Warehouse que suporta operações de escrita (mutações). As fontes de dados acedidas através dos endpoints SQL Analytics (como Lakehouses e bases de dados espelhadas) são apenas de leitura e suportam apenas consultas, não mutações.

Consulte este breve excerto do esquema GraphQL do AdventureWorks. Define um Product tipo com consultas para ler um único produto ou listar todos os produtos, e mutações para criar, atualizar ou eliminar produtos, suportando todos os casos de uso CRUDL (criar, ler, atualizar, eliminar, listar).

{
  type Product {
    ProductID: Int!
    Name: String!
    ProductNumber: String!
    Color: String
    ListPrice: Float!
    SellStartDate: DateTime!
  }

  type Query {
    products(first: Int, filter: ProductFilterInput): ProductConnection
    products_by_pk(ProductID: Int!): Product
  }

  type Mutation {
    createProduct(Name: String!, ProductNumber: String!, ListPrice: Float!, SellStartDate: DateTime!): Product
    updateProduct(ProductID: Int!, Name: String, Color: String, ListPrice: Float): Product
    deleteProduct(ProductID: Int!): Boolean
  }
}

Leia os dados expostos via GraphQL usando qualquer consulta definida no esquema. A products_by_pk consulta recupera um único produto pela sua chave primária:

query MyQuery {
  products_by_pk(ProductID: 680) {
    ProductID
    Name
    ProductNumber
    Color
    ListPrice
  }
}

Response:

{
  "data": {
    "products_by_pk": {
      "ProductID": 680,
      "Name": "HL Road Frame - Black, 58",
      "ProductNumber": "FR-R92B-58",
      "Color": "Black",
      "ListPrice": 1431.50
    }
  }
}

Use mutações, como createProduct para escrever dados e criar um novo produto com os parâmetros necessários.

mutation MyMutation {
  createProduct(
    Name: "Mountain Bike Helmet - Blue", 
    ProductNumber: "HE-M897-B", 
    ListPrice: 89.99,
    SellStartDate: "2025-01-01T00:00:00Z"
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

Response:

{
  "data": {
    "createProduct": {
      "ProductID": 1001,
      "Name": "Mountain Bike Helmet - Blue",
      "ProductNumber": "HE-M897-B",
      "ListPrice": 89.99
    }
  }
}

Variáveis de consulta

Use o painel Variáveis de consulta no lado direito da guia Consulta para passar parâmetros como variáveis para suas consultas ou mutações. As variáveis funcionam como variáveis em outras linguagens de programação. Cada variável é declarada com um nome usado para acessar o valor armazenado nela. Usando o exemplo anterior da mutação, modifica-o ligeiramente para usar variáveis de consulta.

mutation MyMutation ($name: String!, $productNumber: String!, $listPrice: Float!, $sellStartDate: DateTime!){
  createProduct(
    Name: $name, 
    ProductNumber: $productNumber, 
    ListPrice: $listPrice,
    SellStartDate: $sellStartDate
  ) {
    ProductID
    Name
    ProductNumber
    ListPrice
  }
}

Defina variáveis no painel de variáveis de consulta usando o seguinte exemplo.

{
  "name": "Mountain Bike Helmet - Blue",
  "productNumber": "HE-M897-B",
  "listPrice": 89.99,
  "sellStartDate": "2025-01-01T00:00:00Z"
}

As variáveis tornam o código de mutação mais limpo, mais fácil de ler, testar e modificar. Também facilitam a reutilização da mesma mutação com valores diferentes, apenas mudando as variáveis.

Conteúdo relacionado

  • Last updated on