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

  • Artigo

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

Você pode usar Gerenciamento de API para gerenciar APIs do GraphQL – APIs com base 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

Disponibilidade

  • Há suporte para APIs do GraphQL em todas as camadas de serviço do Gerenciamento de API
  • Atualmente, não há suporte para APIs de GraphQL sintéticas em workspaces do 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 no plano 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 costumam retornar 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 que é 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 do usuário e uma consulta para todos os usuários podem ser semelhantes a:

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 operação GET no REST

  • Mutação – Modifica dados do lado do servidor, semelhantes 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.

Próximas etapas