Partilhar via

API de malha para visualização de esquema GraphQL e explorador de esquema

A API Fabric para GraphQL gera automaticamente um esquema que define a estrutura da sua API com base nas fontes de dados que liga. O esquema, escrito em GraphQL Schema Definition Language (SDL), descreve todos os tipos, campos, consultas e mutações disponíveis que os clientes podem usar para interagir com os seus dados.

A vista de esquema fornece uma vista de apenas leitura, baseada em texto, do seu esquema completo do GraphQL, enquanto o explorador de esquemas no painel esquerdo permite-lhe navegar, inspecionar e modificar os objetos expostos através da sua API. Em conjunto, estas ferramentas ajudam-no a compreender a estrutura da sua API e a controlar que dados estão acessíveis aos clientes.

Quem usa a vista de esquema

A vista de esquema e o explorador são valiosos para:

  • Engenheiros de dados configuram quais objetos Fabric lakehouse e armazém de dados expor através do GraphQL
  • Desenvolvedores de aplicações que descobrem os tipos de dados, campos e relações disponíveis em Fabric antes de escreverem consultas
  • Os colaboradores do Fabric Workspace compreendem e gerem a estrutura de acesso aos dados para o seu espaço de trabalho
  • Desenvolvedores de BI ao rever relações de dados no Fabric quando constroem aplicações de análise personalizadas

Use a vista de esquema para explorar a estrutura da sua API e o explorador de esquemas para modificar quais os objetos de dados expostos.

Aceder e explorar o esquema

Pode aceder à vista do esquema a partir do editor de consultas ou diretamente do elemento da API GraphQL. Para abrir a vista de esquema, selecione Schema no canto inferior esquerdo. A vista de esquema apresenta uma versão apenas de leitura, baseada em texto, do seu SDL completo do GraphQL com todos os tipos, campos, consultas e mutações gerados.

A imagem seguinte mostra a vista do esquema com o painel do explorador de esquemas à esquerda:

Captura de tela da tela de exibição de esquema da API, que inclui o explorador de esquema no painel esquerdo.

O explorador de esquemas no painel esquerdo permite-lhe navegar e inspecionar todos os objetos da sua API. O explorador está disponível tanto na vista de esquema como no editor de consultas, facilitando a exploração da estrutura da sua API enquanto escreve consultas.

Expanda os nós no explorador de esquemas para ver:

  • Tipos: Os tipos GraphQL gerados a partir das tabelas e vistas da sua fonte de dados
  • Consultas: Operações de leitura geradas automaticamente para recuperar dados
  • Mutações: Operações de escrita geradas automaticamente para criar, atualizar e eliminar dados (apenas no armazém)

Types

Os tipos representam a estrutura dos seus dados e aparecem sob o nome da fonte de dados a partir da qual foram gerados. A imagem seguinte mostra o tipo SalesOrderDetail gerado a partir da tabela SalesOrderDetail no endpoint de análise SQL do AdventureWorks :

Captura de tela do painel Explorador de esquema, mostrando a lista expandida de tipos disponíveis em uma fonte de dados de exemplo chamada SalesOrderDetail.

Queries

A API gera automaticamente consultas para recuperar dados dos objetos que expõe. Expanda o nó de consultas para ver todas as operações de leitura disponíveis:

Captura de ecrã do painel Explorador de esquemas, mostrando uma lista expandida de consultas geradas automaticamente.

Mutações

Mutações são operações de escrita para criar, atualizar e eliminar dados. Expanda o nó de mutações para ver todas as operações de escrita disponíveis.

Captura de ecrã do painel Explorador de esquemas, mostrando uma lista expandida de mutações geradas automaticamente.

Nota

As mutações são geradas apenas para fontes de dados do Fabric Data Warehouse. Os endpoints de SQL Analytics (Lakehouses e bases de dados espelhadas) são apenas de leitura e suportam apenas consultas. Se não vires mutações no teu explorador de esquemas, verifica se te ligaste a um Fabric Data Warehouse.

Modificar objetos usando o explorador de esquema

Depois de a API gerar o seu esquema inicial, pode usar o explorador de esquemas para refinar o que é exposto através da sua API. O explorador de esquemas oferece opções de gestão que permitem controlar a estrutura da sua API sem modificar as fontes de dados subjacentes. Estas ferramentas são essenciais para manter uma API limpa e bem organizada que expõe apenas os dados de que os seus clientes precisam.

Opções de modificação de acesso

Para modificar um objeto, selecione a elipse (...) ao lado de qualquer tipo no explorador de esquemas. O exemplo seguinte mostra o menu de modificações para o tipo SalesOrderDetail :

Captura de ecrã do explorador de esquemas com as reticências selecionadas, mostrando as opções de menu disponíveis.

Opções de modificação disponíveis

Atualizar esquema - Sincroniza o seu esquema GraphQL com a estrutura mais recente da fonte de dados. Use isto quando adicionar novas tabelas, vistas ou colunas à sua fonte de dados e quiser expô-los através da API. Esta operação descobre e adiciona novos objetos, preservando a sua configuração existente.

Renomear - Altera a forma como o objeto aparece na sua API GraphQL. Isto é útil para criar convenções de nomeação de APIs mais intuitivas ou para esconder detalhes de implementação dos clientes. Por exemplo, pode mudar o nome tbl_SalesOrderDetail para simplesmente SalesOrderDetail. A renomeação afeta apenas o esquema da API e não modifica o objeto de origem subjacente.

Remover do esquema - Remove o objeto da sua API GraphQL e torna-o indisponível para os clientes. Use isto para ocultar dados sensíveis, remover objetos obsoletos ou simplificar a superfície da sua API. Os dados permanecem na sua fonte de dados; apenas a exposição à API é removida.

Gerir relações - Abre a interface de gestão de relações onde pode definir como os objetos se ligam entre si. As relações permitem consultas aninhadas e percurso de grafos, permitindo aos clientes recuperar dados relacionados num único pedido. Para obter mais informações, consulte Gerenciar relacionamentos na API de malha para GraphQL.

Propriedades - Apresenta metadados detalhados sobre o objeto, incluindo o nome original tal como aparece na fonte de dados, o nome do tipo GraphQL, o proprietário e a localização (nome do espaço de trabalho e da fonte de dados). Use isto para verificar como os objetos são mapeados entre a sua fonte de dados e a API GraphQL.

Ativar e desativar consultas e mutações

O recurso habilitar ou desabilitar consultas e mutações fornece aos administradores e desenvolvedores controle granular sobre o acesso e o uso da API. Ele permite que você ative ou desative seletivamente consultas e mutações específicas dentro do esquema GraphQL. Isso permite gerenciar os recursos da API dinamicamente sem modificar o código ou implantar alterações.

Use esta funcionalidade para cenários como:

  • Versionamento da API: Desabilitar operações obsoletas ao transitar clientes para novas versões
  • Janelas de manutenção: Desabilitar temporariamente operações de escrita (mutações) durante a manutenção de dados
  • Segurança e conformidade: Restringa o acesso a operações sensíveis sem as remover do esquema
  • Implementações faseadas: Permitir novas consultas ou mutações para testes antes de as tornar amplamente disponíveis

Consultas e mutações no explorador de esquema têm duas outras opções:

  • Desativar: impede que quaisquer solicitações executem a consulta ou mutação. Se a execução for tentada, um erro será retornado. Depois que uma consulta ou mutação é desabilitada, ocorre uma recarga de esquema e a consulta ou mutação aparece acinzentada no explorador de esquema.

Captura de ecrã da opção de desativação de consulta ou mutação apresentada no explorador de esquemas.

  • Ativar: Permite reativar uma consulta ou mutação anteriormente desativada. A consulta ou mutação fica imediatamente disponível após a operação de recarregamento de esquema que ocorre quando você seleciona a opção Ativar .

Captura de tela da opção ativar consulta de mutação mostrada no explorador de esquema.

Nota

Consultas e mutações geradas automaticamente a partir de procedimentos armazenados comportam-se de forma diferente das geradas a partir de tabelas ou vistas. Só podem ser apagados, não desativados. Após a eliminação, pode adicioná-los novamente usando as opções Obter Dados ou Atualizar Esquema. Para mais informações, consulte Procedimentos armazenados.

Conteúdos relacionados

  • Last updated on