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

  • Artigo

APLICA-SE A: Todas as camadas de gerenciamento de API

Você pode usar o Gerenciamento de API para gerenciar APIs do GraphQL - APIs baseadas na linguagem de consulta do 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 de que precisam. Saiba mais sobre o GraphQL

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

Pass-through GraphQL Synthetic GraphQL
▪️ API de passagem para o ponto de extremidade de serviço GraphQL existente

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

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

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

▪️ Desenvolva esquemas GraphQL e clientes baseados em GraphQL enquanto consome dados de APIs herdadas

Disponibilidade

  • As APIs do GraphQL são suportadas em todas as camadas de serviço do Gerenciamento de API
  • Atualmente, as APIs sintéticas do GraphQL não são suportadas nos espaços de trabalho de Gerenciamento de API
  • O suporte para assinaturas do GraphQL em APIs sintéticas do GraphQL está atualmente em visualização e não está disponível na camada Consumo

O que é o GraphQL?

O GraphQL é uma linguagem de consulta de código aberto padrão do setor para APIs. Ao contrário das APIs no estilo REST projetadas em torno de ações sobre recursos, as APIs do GraphQL oferecem suporte a um conjunto mais amplo de casos de uso e se concentram em tipos de dados, esquemas e consultas.

A especificação 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 para 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 pesquisar 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 do serviço GraphQL em tempo real.

Esquema e tipos

No Gerenciamento de API, adicione uma API GraphQL de um esquema GraphQL, recuperada de um endpoint de back-end da API GraphQL ou carregada por você. Um esquema 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 GraphQL básico para dados do usuário e uma consulta para todos os usuários podem se parecer com:

type Query {
    users: [User]
}

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

Tipos de operação

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

  • Consulta - Busca dados, semelhante a uma GET operação em REST

  • Mutação - Modifica dados do lado do servidor, semelhante a uma PUT operação ou PATCH em REST

  • Subscrição - Permite notificar os clientes subscritos em tempo real sobre alterações aos dados no serviço GraphQL

    Por exemplo, quando os dados são modificados através de uma mutação GraphQL, os clientes subscritos podem ser automaticamente notificados sobre a alteração.

    Importante

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

Outros tipos

O Gerenciamento de API suporta os tipos de união e interface em esquemas GraphQL.

Resolvedores

Os resolvedores cuidam de mapear o 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 de resolução seria responsável por retornar dados para a users consulta 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 GraphQL de passagem.

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

Data source Política de resolução
Fonte de dados baseada em HTTP (REST ou SOAP API) http-fonte de dados
Base de dados do Cosmos DB cosmosdb-fonte de dados
Base de dados SQL do Azure sql-data-source

Por exemplo, um resolvedor baseado em API HTTP para a consulta anterior users pode mapear para uma GET operação 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 obter mais informações sobre como configurar um resolvedor, consulte Configurar um resolvedor GraphQL.

Gerenciar APIs do GraphQL

  • Proteja as APIs do GraphQL aplicando políticas de controle de acesso existentes e uma política de validação do GraphQL para proteger contra ataques específicos do GraphQL.
  • Explore o esquema do GraphQL e execute consultas de teste nas APIs do GraphQL nos portais do Azure e do desenvolvedor.

Próximos passos