Compartilhar via

Introspecção e exportação de esquema da API do Fabric para GraphQL

Ao criar aplicativos ou integrar ferramentas externas à API do Fabric para GraphQL, você precisa entender a estrutura da API , quais tipos estão disponíveis, quais campos eles contêm e como eles se relacionam entre si. Se você estiver gerando código do cliente, criando documentação ou configurando ferramentas de gerenciamento de API, acessar sua definição de esquema é essencial.

A API do Fabric para GraphQL fornece dois mecanismos complementares para recuperar informações de esquema: introspecção para consultas de runtime programáticas e exportação de esquema para obter um arquivo de esquema completo. Ambos os métodos oferecem acesso ao mesmo esquema subjacente, mas cada um deles atende a fluxos de trabalho diferentes e casos de uso.

Dica

Deseja ver a introspecção em ação? Experimente o tutorial Conectar agentes de IA à API do Fabric para GraphQL com um servidor MCP (Protocolo de Contexto de Modelo) local. Este guia prático mostra como os agentes de IA usam a introspecção para descobrir e consultar automaticamente seus dados do Fabric usando linguagem natural.

Quem usa introspecção e exportação de esquema

A introspecção e a exportação de esquema são valiosas para:

  • Desenvolvedores de aplicativos que criam clientes que consomem dados do Fabric e precisam gerar código com segurança de tipo
  • Colaboradores do workspace do Fabric que entendem as estruturas de dados disponíveis e testam o acesso a dados
  • Ferramentas de desenvolvimento e IDEs que fornecem preenchimento automático e APIs do IntelliSense para Fabric GraphQL
  • Integrações do Gerenciamento de API do Azure que roteiam e protegem o tráfego do Fabric GraphQL no nível da empresa
  • Administradores de fabric auditando estruturas de dados expostas e validando controles de acesso
  • Agentes e assistentes de IA usando o PROTOCOLO MCP (Model Context Protocol) para descobrir e consultar dados do Fabric naturalmente
  • Desenvolvedores do Power Platform que entendem os esquemas de dados do Fabric antes de criar integrações
  • Pipelines de CI/CD que rastreiam versões de esquema do GraphQL do Fabric e validam a compatibilidade entre ambientes

Escolha introspecção quando precisar consultar informações de esquema programaticamente em runtime, como ativar ferramentas de desenvolvimento, habilitar agentes de IA ou implementar recursos dinâmicos do cliente. Escolha exportação de esquema quando precisar de um arquivo de esquema completo para uso offline, controle de versão, integração de gateway de API ou compartilhamento com equipes externas.

  • Introspecção: consulte seu esquema programaticamente usando o sistema de introspecção GraphQL, que faz parte do padrão GraphQL. As consultas de introspecção permitem que você descubra tipos, campos e relações dinamicamente e elas alimentam muitas ferramentas de desenvolvimento do GraphQL.

  • Exportação de esquema: baixe um arquivo SDL completo (Linguagem de Definição de Esquema graphQL) que contém toda a definição de esquema para uso offline, compartilhamento ou integração de ferramentas.

Introspecção

Por padrão, a introspecção está desabilitada em sua API para itens do GraphQL. Essa configuração só pode ser alternada por administradores de espaço de trabalho. Todos os outros usuários verão um controle deslizante desabilitado.

Para habilitar a introspecção:

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

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

  2. Na navegação à esquerda, selecione a página Introspecção .

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

  3. Selecione a alternância para habilitar a introspecção. Habilitar a introspecção divulga informações do esquema para todos os usuários com acesso ao endpoint da API.

  4. Uma caixa de diálogo de confirmação será exibida. Selecione Confirmar para habilitar a introspecção ou Cancelar para deixá-la desabilitada.

    Captura de tela que mostra a caixa de diálogo de confirmação para habilitar introspecção.

Exemplo de consulta de introspecção

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

  1. Crie uma nova consulta no editor do GraphQL. Selecione o ícone de adição + ao lado das guias existentes para abrir uma nova guia de consulta.

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

  2. Insira a seguinte consulta de introspecção no editor:

    query {
    __schema {
        types{
            name
        }
    }
}

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

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

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

Consultas de introspecção podem retornar grandes quantidades de informações. Você pode restringir o escopo do que você consulta sendo mais específico em sua solicitação de introspecção. Por exemplo, em vez de consultar todos os tipos, você pode consultar um tipo específico:

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

A execução da consulta retorna informações detalhadas 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
          }
        }
      ]
    }
  }
}

Os padrões comuns de filtragem ao processar resultados de introspecção incluem:

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

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

Exportar esquema

Quando precisar de uma cópia completa e offline da definição de esquema, use o recurso de exportação de esquema diretamente do portal do Fabric. Abra sua API para GraphQL e selecione Exportar esquema na barra de ferramentas. Seu navegador baixa um arquivo SDL (Linguagem de Definição de Esquema) que contém sua definição de esquema completa.

Captura de tela que mostra o botão exportar esquema.

Noções básicas sobre o arquivo SDL

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

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

Você pode abrir o arquivo SDL em qualquer editor de texto para revisar sua estrutura de esquema. Isso é particularmente útil para entender a superfície de API completa antes de integrá-la em seus aplicativos.

Usando o esquema exportado

Casos de uso comuns para o arquivo SDL exportado incluem:

  • Integração de gateway de API: importar no Azure API Management para adicionar autenticação, limitação de velocidade e cache
  • Configuração do ambiente de desenvolvimento: configurar o IntelliSense no Visual Studio Code para preenchimento automático e validação
  • Controle de versão: Confirme-se com o Git ou outros sistemas de controle do código-fonte para acompanhar a evolução do esquema ao longo do tempo
  • Colaboração em equipe: Compartilhe com parceiros externos ou equipes de desenvolvimento que precisam entender sua estrutura de API
  • Geração de código: use com geradores de código GraphQL para criar clientes com tipagem segura em TypeScript, C#, Java ou outras linguagens de programação
  • Documentação: gerar documentação de referência da API usando ferramentas como GraphQL Voyager ou GraphQL Markdown

Ao contrário das consultas de introspecção, a exportação de esquema não exige que a introspecção seja habilitada e funcione independentemente das configurações de introspecção da API. Isso torna uma maneira confiável de acessar sua definição de esquema para fins administrativos e de desenvolvimento.

Gerenciando alterações de esquema

Os esquemas graphQL podem evoluir ao longo do tempo à medida que você adiciona novos tipos, campos ou recursos à sua API. Quando o esquema é alterado, os arquivos SDL exportados ficam desatualizados. Considere estas práticas:

  • Exportar novamente após as alterações: baixe um novo arquivo SDL sempre que modificar o esquema de API no Fabric. As alterações de esquema incluem adicionar fontes de dados, modificar tipos expostos ou atualizar definições de campo.
  • Controle de versão: confirme cada esquema exportado para o sistema de controle do código-fonte com mensagens de confirmação descritivas. Isso cria uma trilha de auditoria da evolução do esquema e permite a reversão, se necessário.
  • Comunicação: se as equipes ou aplicativos externos dependerem do esquema, notifique-os sobre alterações significativas. Embora o GraphQL dê suporte a alterações aditivas sem interromper consultas existentes, a remoção ou renomeação de campos pode afetar os clientes.
  • Automação: para pipelines de CI/CD, considere automatizar as exportações de esquema como parte do processo de implantação para garantir que a documentação e as ferramentas permaneçam sincronizadas com sua API.

A pessoa responsável por modificar o esquema de API (normalmente um engenheiro de dados ou desenvolvedor de API) deve exportar e versão do esquema atualizado para manter a consistência entre a API do Fabric e sistemas externos que dependem dele.

Conteúdo relacionado

  • Last updated on