Adicionar uma API do GraphQL sintético e configurar resolvedores de campo

  • Artigo

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

No Gerenciamento de API, você pode adicionar uma API do GraphQL em um dos dois modelos: passagem para um ponto de extremidade do GraphQL existente ou importação de um esquema do GraphQL e criação de uma API do GraphQL sintético com resolvedores de campo personalizados. Para obter mais informações, confira a Visão geral do GraphQL.

Observação

Atualmente, esse recurso não está disponível em workspaces.

Neste artigo você vai:

  • Importe um esquema de GraphQL para sua instância de Gerenciamento de API
  • Configurar um resolvedor para uma consulta do GraphQL usando um ponto de extremidade HTTP existente
  • Testar a API do GraphQL

Se você quiser expor um ponto de extremidade do GraphQL existente como uma API, consulte Importar uma API do GraphQL.

Pré-requisitos

  • Uma instância de Gerenciamento de API existente. Crie uma, se ainda não tiver.
  • Um arquivo de esquema do GraphQL válido com a extensão .graphql.
  • Um ponto de extremidade do GraphQL de back-end é opcional para esse cenário.

Navegar até a instância de Gerenciamento de API

  1. No portal do Azure, pesquise e selecione serviços de Gerenciamento de API.

    Selecione Serviços de Gerenciamento de API

  2. Na página Serviços de Gerenciamento de API, selecione a sua instância de Gerenciamento de API.

    Selecione a sua instância de Gerenciamento de API

Adicionar um esquema GraphQL

  1. No menu de navegação lateral, na seção APIs, selecione APIs.

  2. Em Definir uma nova API, selecione o ícone GraphQL.

    Captura de tela da seleção do ícone do GraphQL na lista de APIs.

  3. Na caixa de diálogo, selecione Completo e preencha os campos de formulário necessários.

    Captura de tela dos campos para criar uma API do GraphQL.

    Campo Description
    Nome de exibição O nome pelo qual a API do GraphQL será exibida.
    Nome Nome bruto da API do GraphQL. Preenche automaticamente conforme você digita o nome de exibição.
    Tipo do GraphQL Selecione GraphQL sintético para importar de um arquivo de esquema do GraphQL.
    Ponto de extremidade do GraphQL de fallback Opcionalmente, insira uma URL com um nome de ponto de extremidade da API do GraphQL. Gerenciamento de API passa consultas GraphQL para esse ponto de extremidade quando um resolvedor personalizado não é definido para um campo.
    Descrição Adicione uma descrição da sua API.
    Esquema de URL Faça uma seleção com base no ponto de extremidade do GraphQL. Selecione uma das opções que inclui um esquema de WebSocket (WS ou WSS) se a API do GraphQL incluir o tipo de assinatura. Seleção padrão: HTTP(S).
    Sufixo da URL da API Adicione um sufixo de URL para identificar essa API específica nesta instância de Gerenciamento de API. Ele deve ser exclusivo nessa instância do Gerenciamento de API.
    URL base Campo não editável exibindo a URL base da API
    Marcas Associe sua API do GraphQL a marcações novas ou existentes.
    Produtos Associe sua API do GraphQL a um produto para publicá-la.
    Controlar a versão desta API? Selecione para aplicar um esquema de controle de versão à API do GraphQL.

  4. Selecione Criar.

  5. Depois que a API for criada, procure ou modifique o esquema na guia Design.

Configurar resolvedor

Configure um resolvedor para mapear um campo no esquema a um ponto de extremidade HTTP existente. As etapas de alto nível são fornecidas aqui. Para mais detaljes, confira Configurar um resolvedor do GraphQL.

Suponha que você importou o esquema GraphQL básico a seguir e queria configurar um resolvedor para a consulta de usuários .

type Query {
    users: [User]
}

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

  1. No menu de navegação lateral, na seção APIs, selecione APIs> na sua API do GraphQL.

  2. Na guia Esquema, examine o esquema de um campo em um tipo de objeto em que você deseja configurar um resolvedor.

    1. Selecione um campo e, na margem esquerda, passe o ponteiro.

    2. Selecione + Adicionar Resolvedor

      Captura de tela da adição de um resolvedor do GraphQL no portal.

  3. Na página Criar Resolvedor:

    1. Atualize a propriedade Name se desejar, insira opcionalmente uma Descrição e confirme ou atualize as seleções Tipo e Campo.
    2. Em Fonte de dados, selecione API HTTP.

  4. No editor Política do resolvedor, atualize o elemento <http-data-source> com elementos filho para seu cenário. Por exemplo, o resolvedor a seguir recupera o campo usuários usando uma chamada GET em uma fonte de dados HTTP existente.

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

    Captura de tela da configuração de uma política de resolvedor no portal.

  5. Selecione Criar.

  6. Para resolver dados de outro campo no esquema, repita as etapas anteriores para criar um resolvedor.

Dica

Ao editar uma política de resolvedor, selecione Executar teste para verificar a saída da fonte de dados, que você pode validar no esquema. Se ocorrerem erros, a resposta incluirá informações de solução de problemas.

Testar a API do GraphQL

  1. Navegue até sua instância de Gerenciamento de API.

  2. No menu de navegação lateral, na seção APIs, selecione APIs.

  3. Em Todas as APIs, selecione sua API do GraphQL.

  4. Selecione a guia Teste para acessar o console de teste.

  5. Em Cabeçalhos:

    1. Selecione o cabeçalho menu suspenso Nome.
    2. Insira o valor para o campo Valor.
    3. Adicione mais cabeçalhos selecionando + Adicionar cabeçalho.
    4. Exclua os cabeçalhos usando o ícone da lixeira.

  6. Se você adicionou um produto à API do GraphQL, aplique o escopo do produto em Aplicar escopo do produto.

  7. Em Editor de consultas, faça o seguinte:

    1. Selecione pelo menos um campo ou subcampo da lista no menu lateral. Os campos e subcampos selecionados são exibidos no editor de consultas.

    2. Comece a digitar no editor de consultas para compor uma consulta.

      Captura de tela demonstrando a adição de campos ao editor de consultas.

  8. Em Variáveis de consulta, adicione variáveis para reutilizar a mesma consulta ou mutação e passar valores diferentes.

  9. Selecione Enviar.

  10. Veja a Resposta.

    Captura de tela da exibição da resposta da consulta de teste.

  11. Repita as etapas anteriores para testar cargas diferentes.

  12. Quando o teste for concluído, saia do console de teste.

Proteger a API do GraphQL

Proteja sua API GraphQL aplicando as políticas existentes de autenticação e autorização e uma política de validação GraphQL para proteger contra ataques específicos do GraphQL.

Próximas etapas

Transformar e proteger uma API publicada