Compartilhar via

Visão geral das APIs do GraphQL no Gerenciamento de API do Azure

APLICA-SE A: todas as camadas do Gerenciamento de API

Você pode usar o Gerenciamento de API para gerenciar APIs do GraphQL, que são APIs baseadas na linguagem de consulta GraphQL. O GraphQL fornece uma descrição completa e compreensível dos dados em uma API, dando aos clientes o poder de recuperar com eficiência exatamente os dados necessários. Saiba mais sobre o GraphQL.

Gerenciamento de API ajuda a importar, gerenciar, proteger, testar, publicar e monitorar APIs do GraphQL. Você pode escolher um dos dois modelos de API:

GraphQL de passagem GraphQL sintético
▪️ API de passagem para o ponto de extremidade de serviço do GraphQL existente

▪️ Suporte para consultas, mutações e assinaturas do GraphQL		 ▪️ API baseada em um esquema personalizado do GraphQL

▪️ Suporte para consultas, mutações e assinaturas do GraphQL

▪️ Configurar resolvedores personalizados, por exemplo, para fontes de dados HTTP

▪️ Desenvolver esquemas GraphQL e clientes baseados em GraphQL ao consumir dados de APIs herdadas

▪️ As assinaturas sintéticas não exigem resolvedores. Veja a política publish-event.

Disponibilidade

  • As APIs do GraphQL têm suporte em todas as camadas de serviço de Gerenciamento de API.
  • Atualmente, não há suporte para APIs sintéticas do GraphQL nos workspaces de Gerenciamento de API.
  • O suporte a assinaturas do GraphQL em APIs sintéticas do GraphQL está atualmente em versão prévia e não está disponível na camada de Consumo.

O que é o GraphQL?

O GraphQL é uma linguagem de consulta de código aberto para APIs, que segue os padrões do setor. Ao contrário das APIs de estilo REST projetadas para ações em recursos, as APIs do GraphQL são compatíveis com um conjunto mais amplo de casos de uso e se concentram em tipos de dados, esquemas e consultas.

A especificação do GraphQL resolve explicitamente problemas comuns enfrentados por aplicativos Web cliente que dependem de APIs REST:

  • Pode ser necessário um grande número de solicitações para atender às necessidades de dados de uma única página.
  • As APIs REST geralmente retornam mais dados do que o necessário para a página que está sendo renderizada.
  • O aplicativo cliente precisa sondar para obter novas informações.

Usando uma API do GraphQL, o aplicativo cliente pode especificar os dados necessários para renderizar uma página em um documento de consulta enviado como uma única solicitação para um serviço GraphQL. Um aplicativo cliente também pode assinar atualizações de dados enviadas por push do serviço GraphQL em tempo real.

Esquema e tipos

Em Gerenciamento de API, adicione uma API do GraphQL de um esquema GraphQL, recuperado de um ponto de extremidade da API do GraphQL de back-end ou carregado por você. Um esquema do GraphQL descreve:

  • Tipos de objeto de dados e campos que os clientes podem solicitar de uma API do GraphQL.
  • Tipos de operação permitidos nos dados, como consultas.
  • Outros tipos, como uniões e interfaces, que fornecem flexibilidade e controle adicionais sobre os dados.

Por exemplo, um esquema básico do GraphQL para dados de usuário e uma consulta para todos os usuários pode ser semelhante ao seguinte:

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

Tipos de operação

O Gerenciamento de API dá suporte para os seguintes tipos de operações em esquemas do GraphQL. Para obter mais informações sobre esses tipos de operação, consulte a especificação do GraphQL.

  • Consulta: busca dados, semelhante a uma GET operação no REST.

  • Mutação: Modifica dados do lado do servidor, semelhante a uma operação PUT ou PATCH no REST.

  • Assinatura: habilita a notificação de clientes inscritos em tempo real sobre alterações nos dados no serviço GraphQL.

    Por exemplo, quando os dados são modificados por meio de uma mutação do GraphQL, os clientes inscritos podem ser notificados automaticamente sobre a alteração.

    Importante

    O Gerenciamento de API dá suporte a assinaturas implementadas usando o protocolo WebSocket graphql-ws. Não há suporte para consultas e mutações no WebSocket.

Outros tipos

O Gerenciamento de API dá suporte aos tipos união e interface em esquemas GraphQL.

Resolvedores

Resolvedores cuidam do mapeamento do esquema GraphQL para dados de back-end, produzindo os dados para cada campo em um tipo de objeto. A fonte de dados pode ser uma API, um banco de dados ou outro serviço. Por exemplo, uma função resolvedora seria responsável por retornar dados para a consulta users no exemplo anterior.

No Gerenciamento de API, você pode criar um resolvedor para mapear um campo em um tipo de objeto para uma fonte de dados de back-end. Você configura resolvedores para campos em esquemas sintéticos da API do GraphQL, mas também pode configurá-los para substituir os resolvedores de campo padrão usados pelas APIs do GraphQL de passagem.

Atualmente, o Gerenciamento de API dá suporte a resolvedores baseados em fontes de dados API HTTP, Cosmos DB e SQL do Azure para retornar os dados para os campos em um esquema GraphQL. Cada resolvedor é configurado usando uma política personalizada para se conectar à fonte de dados e recuperar os dados:

Fonte de dados Política do resolvedor
Fonte de dados baseada em HTTP (API REST ou SOAP) http-data-source
Banco de dados do Cosmos DB cosmosdb-data-source
banco de dados SQL do Azure sql-data-source

Por exemplo, um resolvedor baseado em API HTTP para a consulta users anterior, pode ser mapeado para uma operação GET em uma API REST de back-end:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>https://myapi.contoso.com/api/users</set-url>
    </http-request>
</http-data-source>

Para mais informações sobre como configurar um resolvedor, confira como Configurar um resolvedor GraphQL.

Gerenciar APIs do GraphQL

  • Proteger API do GraphQL aplicando tanto políticas de controle de acesso existentes como políticas de validação de GraphQL para protegê-las de ataques específicos de GraphQL.
  • Explore o esquema GraphQL e execute consultas de teste nas APIs do GraphQL nos portais do Azure e do desenvolvedor.

Conteúdo relacionado

  • Last updated on