Partilhar via

API de malha para introspeção do GraphQL e exportação de esquema

Quando constrói aplicações ou integra ferramentas externas com a sua API Fabric para GraphQL, precisa de compreender a estrutura da sua API—que tipos estão disponíveis, que campos contêm e como se relacionam entre si. Quer esteja a gerar código do cliente, a criar documentação ou a configurar ferramentas de gestão de APIs, aceder à definição do seu esquema é essencial.

A API Fabric para GraphQL fornece dois mecanismos complementares para recuperar informação de esquema: introspeção para consultas programáticas em tempo de execução e exportação de esquemas para obter um ficheiro de esquema completo. Ambos os métodos dão-te acesso ao mesmo esquema subjacente, mas cada um serve fluxos de trabalho e casos de uso diferentes.

Sugestão

Queres ver a introspeção em ação? Experimenta o tutorial Ligar Agentes AI à API Fabric para GraphQL com um servidor local Model Context Protocol (MCP). Este guia prático mostra como os agentes de IA usam a introspeção para descobrir e consultar automaticamente os seus dados do Fabric usando linguagem natural.

Quem usa introspeção e exportação de esquemas

A introspeção e a exportação de esquemas são valiosas para:

  • Desenvolvedores de aplicações que desenvolvem clientes que consomem dados Fabric e precisam de gerar código fortemente tipado
  • Contribuidores do espaço de trabalho Fabric que compreendem as estruturas de dados disponíveis e testam o acesso aos dados
  • Ferramentas de desenvolvimento e IDEs que fornecem autocomplete e IntelliSense para APIs GraphQL de Fabric
  • Integrações Azure API Management que encaminham e protegem o tráfego Fabric GraphQL ao nível empresarial
  • Administradores de Fabric auditar estruturas de dados expostas e a validar controlos de acesso
  • Agentes e assistentes de IA usando o Protocolo de Contexto do Modelo (MCP) para descobrir e consultar dados Fabric de forma natural
  • Desenvolvedores Power Platform devem compreender os esquemas de dados Fabric antes de desenvolver integrações
  • Pipelines CI/CD que monitorizam as versões dos esquemas do Fabric GraphQL e validam a compatibilidade entre os ambientes

Escolha a introspeção quando precisar de consultar informação de esquema programáticamente em tempo de execução, como ligar ferramentas de desenvolvimento, ativar agentes de IA ou implementar funcionalidades dinâmicas do cliente. Escolha exportação de esquema quando precisar de um ficheiro de esquema completo para uso offline, controlo de versões, integração de gateway API ou partilha com equipas externas.

  • Introspeção: Consulte o seu esquema programaticamente usando o sistema de introspeção GraphQL, que faz parte do padrão GraphQL. As consultas de introspeção permitem-lhe descobrir tipos, campos e relações de forma dinâmica, e alimentam muitas ferramentas de desenvolvimento GraphQL.

  • Exportação de esquema: Descarregue um ficheiro completo SDL (GraphQL Schema Definition Language) que contenha toda a definição do seu esquema para uso offline, partilha ou integração com ferramentas.

Introspeção

Por padrão, a introspeção está desativada em sua API para itens do GraphQL. Esta definição só pode ser ativada pelos administradores do espaço de trabalho. Todos os outros usuários verão um controle deslizante desativado.

Para permitir a introspeção:

  1. Selecione o ícone Definições de engrenagem da API no menu superior.

    Captura de tela que mostra a barra do portal mostrando o botão de engrenagem de configurações.

  2. No painel de navegação à esquerda, selecione a opção Introspeção.

    Captura de tela que mostra o controle deslizante de configuração de introspeção.

  3. Seleciona a opção para ativar a introspeção. Ativar a introspeção expõe a informação do esquema a todos os utilizadores com acesso ao endpoint da API.

  4. É apresentado um diálogo de confirmação. Selecione Confirmar para ativar a introspeção ou Cancelar para deixar desativado.

    Captura de tela que mostra a caixa de diálogo de confirmação de ativação de introspeção.

Exemplo de consulta de introspeção

Aqui está um exemplo rápido de uma consulta de introspeção para recuperar tipos disponíveis do esquema:

  1. Crie uma nova consulta no editor GraphQL. Selecione o ícone de adição + ao lado dos separadores existentes para abrir um novo separador de consulta.

    Captura de ecrã que mostra o novo botão de consulta no editor GraphQL.

  2. Introduza a seguinte pergunta de introspeção no editor:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Selecione o botão Executar para executar a consulta.

  4. O painel de resultados mostra uma lista de todos os tipos definidos no esquema.

    Captura de tela que mostra o exemplo de consulta de introspeção.

As consultas de introspeção podem devolver grandes quantidades de informação. Podes restringir o âmbito do que questionas sendo mais específico no teu pedido de introspeção. Por exemplo, em vez de consultar todos os tipos, pode consultar um tipo específico:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

Executar a consulta retorna informação detalhada sobre o ProductCategory tipo:

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

Padrões comuns de filtragem ao processar resultados de introspeção incluem:

  • Excluindo tipos que começam por sublinhados duplos (__), que são tipos de sistemas GraphQL
  • Incluir tipos que começam com prefixos específicos como ProductCategory

Estes exemplos demonstram a sintaxe padrão de introspeção do GraphQL que funciona em qualquer implementação do GraphQL. Esta visão geral cobre padrões básicos de introspeção — para detalhes abrangentes sobre o sistema de introspeção, técnicas avançadas de consulta e capacidades adicionais, consulte a documentação oficial da GraphQL Foundation sobre introspeção.

Esquema de exportação

Quando precisar de uma cópia completa e offline da definição do seu esquema, use a funcionalidade de exportação do esquema diretamente do portal do Fabric. Abra a sua API para o GraphQL e selecione Exportar esquema na barra de ferramentas. O seu navegador descarrega um ficheiro SDL (Linguagem de Definição de Esquemas) contendo a definição completa do seu esquema.

Captura de tela que mostra o botão de esquema de exportação.

Compreender o ficheiro SDL

O ficheiro exportado utiliza a Linguagem de Definição de Esquema (SDL) do GraphQL, um formato legível por humanos que define os tipos, campos e relações da sua API. O ficheiro SDL inclui:

  • Tipos de objetos que representam as suas entidades de dados com os seus campos
  • Operações de consulta que definem como recuperar dados
  • Operações de mutação para criar, atualizar ou eliminar dados
  • Argumentos de campo que especificam parâmetros de entrada e os seus tipos
  • Descrições de tipos que fornecem documentação para cada elemento

Podes abrir o ficheiro SDL em qualquer editor de texto para rever a estrutura do teu esquema. Isto é particularmente útil para compreender toda a superfície da API antes de a integrar nas suas aplicações.

Utilização do esquema exportado

Casos de uso comuns para o ficheiro SDL exportado incluem:

  • Integração com gateways de API: Importar no Azure API Management para adicionar autenticação, limitação de taxa e cache
  • Configuração do ambiente de desenvolvimento: Configurar o IntelliSense no Visual Studio Code para autocompletar e validar
  • Controlo de versões: Compromete-se com o Git ou outros sistemas de controlo de versões para acompanhar a evolução do esquema ao longo do tempo
  • Colaboração em equipa: Partilhe com parceiros externos ou equipas de desenvolvimento que precisam de compreender a estrutura da sua API
  • Geração de código: Utilizar com geradores de código GraphQL para criar clientes seguros para tipos em TypeScript, C#, Java ou outras linguagens
  • Documentação: Gerar documentação de referência API usando ferramentas como GraphQL Voyager ou GraphQL Markdown

Ao contrário das consultas de introspeção, a exportação de esquema não requer que a introspeção esteja ativada e funciona independentemente das definições de introspeção da tua API. Isto torna-o uma forma fiável de aceder à definição do seu esquema para fins administrativos e de desenvolvimento.

Gerir alterações de esquemas

Os esquemas GraphQL podem evoluir ao longo do tempo à medida que adiciona novos tipos, campos ou capacidades à sua API. Quando o esquema muda, os ficheiros SDL exportados ficam desatualizados. Considere estas práticas:

  • Reexporte após alterações: Descarregue um ficheiro SDL novo sempre que modificar o seu esquema API no Fabric. As alterações de esquema incluem adicionar fontes de dados, modificar tipos expostos ou atualizar definições de campos.
  • Controlo de versões: Faça um commit de cada esquema exportado no seu sistema de controlo de versões com mensagens de commit descritivas. Isto cria um registo de auditoria da evolução do esquema e permite o rollback, se necessário.
  • Comunicação: Se equipas ou aplicações externas dependerem do seu esquema, notifique-os sobre alterações significativas. Embora o GraphQL suporte alterações aditivas sem quebrar consultas existentes, a remoção ou renomeação de campos pode afetar os clientes.
  • Automação: Para pipelines CI/CD, considere automatizar a exportação de esquemas como parte do seu processo de implementação para garantir que a documentação e as ferramentas se mantêm sincronizadas com a sua API.

A pessoa responsável por modificar o esquema da API (normalmente um engenheiro de dados ou programador de API) deve exportar e versionar o esquema atualizado para manter a consistência entre a API Fabric e os sistemas externos que dela dependem.

Conteúdo relacionado

  • Last updated on