Configurar um resolvedor do GraphQL

  • Artigo

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

Configurar um resolvedor para recuperar ou definir dados para um campo do GraphQL em um tipo de objeto especificado em um esquema GraphQL. O esquema deve ser importado para o Gerenciamento de API como uma API do GraphQL.

Atualmente, o Gerenciamento de API dá suporte a resolvedores que podem acessar as seguintes fontes de dados:

Observações importantes

  • Um resolvedor é um recurso que contém uma definição de política que é invocada somente quando um tipo de objeto e um campo correspondentes no esquema são executados.
  • Cada resolvedor resolve dados para um único campo. Para resolver dados para vários campos, configure um resolvedor separado para cada um.
  • As políticas no escopo do resolvedor são avaliadas após qualquer política inbound e backend no pipeline de execução da política. Eles não herdam políticas de outros escopos. Para obter mais informações, confira Políticas no Gerenciamento de API.
  • Você pode configurar políticas no escopo da API para uma API de GraphQL, independentemente das políticas no escopo do resolvedor. Por exemplo, adicione uma política validate-graphql-request ao escopo inbound para validar a solicitação antes que o resolvedor seja invocado. Configure políticas no escopo da API na guia Políticas de API para a API.

Pré-requisitos

Criar um resolvedor

As etapas a seguir criam um resolvedor usando uma fonte de dados baseada em HTTP. As etapas gerais são semelhantes para qualquer resolvedor que use uma fonte de dados compatível.

  1. No portal do Azure, navegue até a instância do Gerenciamento de API.

  2. No menu à esquerda, selecione APIs e depois o nome de sua API do GraphQL.

  3. 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 de um campo no esquema GraphQL no portal.

  4. 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. Selecione a Fonte de dados do resolvedor. Para esse exemplo, selecione API HTTP.

  5. No editor de Política do resolvedor, atualize a política http-data-source com elementos filho para seu cenário.

    1. Atualize o elemento http-request necessário com políticas para transformar a operação GraphQL em uma solicitação HTTP.

    2. Opcionalmente, adicione um elemento http-response e adicione políticas filho para transformar a resposta HTTP do resolvedor. Se o elemento http-response não for especificado, a resposta será retornada como uma cadeia de caracteres bruta.

    3. Selecione Criar.

      Captura de tela do editor de política de resolvedor no portal.

    O resolvedor é anexado ao campo e aparece na guia Resolvedores.

    Captura de tela da lista de resolvedores para a API do GraphQL no portal.

Gerenciar resolvedores

Liste e gerencie os resolvedores de uma API de GraphQL na guia Resolvedores da API.

Captura de tela do gerenciamento de resolvedores para a API GraphQL no portal.

Na guia Resolvedores:

  • A coluna Vinculado indica se o resolvedor está configurado para um campo que está atualmente no esquema GraphQL. Se um resolvedor não estiver vinculado, ele não poderá ser invocado.

  • No menu de contexto (...) para um resolvedor, localize comandos para Clonar, Editar ou Excluir um resolvedor. Clone um resolvedor listado e crie rapidamente um resolvedor semelhante que é direcionado a um tipo e campo diferentes.

  • Você pode criar um novo resolvedor selecionando + Criar.

Editar e testar um resolvedor

Quando você edita um único resolvedor, a página Editar resolvedor é aberta. Você poderá:

  • Atualize a política de resolvedor e, opcionalmente, a fonte de dados. Alterar a fonte de dados substitui a política de resolvedor atual.

  • Altere o tipo e o campo que o resolvedor tem como destino.

  • Teste e depure a configuração do resolvedor. Ao editar a política de resolvedor, selecione Executar teste para verificar a saída da fonte de dados, que você pode validar em relação ao esquema. Se ocorrerem erros, a resposta incluirá informações de solução de problemas.

    Captura de tela da edição de um resolvedor no portal.

Contexto do GraphQL

  • O contexto da solicitação e da resposta do resolvedor (se especificado) difere do contexto da solicitação original da API do gateway:
    • context.GraphQL as propriedades são definidas como os argumentos (Arguments) e o objeto pai (Parent) para a execução atual do resolvedor.
    • O contexto da solicitação contém argumentos que são transmitidos na consulta do GraphQL como o corpo.
    • O contexto da resposta é a resposta da chamada independente feita pelo resolvedor, não o contexto da resposta completa da solicitação do gateway. A variável context passada por meio dos pipelines de solicitação e de resposta é aumentada com o contexto do GraphQL, quando usada com um resolvedor do GraphQL.

context.GraphQL.parent

O context.GraphQL.parent é definido como o objeto pai para a execução atual do resolvedor. Considere o esquema parcial a seguir:

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

Além disso, considere uma consulta GraphQL para todas as informações de um blog específico:

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

Se você definir um resolvedor para o campo comments no tipo Blog, convém entender qual ID de blog usar. Você pode obter a ID do blog usando context.GraphQL.Parent["id"] conforme mostrado no seguinte resolvedor:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

context.GraphQL.Arguments

Os argumentos para uma consulta GraphQL parametrizada são adicionados ao context.GraphQL.Arguments. Por exemplo, considere as duas consultas a seguir:

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

Essas consultas são duas maneiras de chamar o resolvedor getComment. O GraphQL envia o seguinte payload JSON:

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

Você pode definir o resolvedor da seguinte maneira:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

Próximas etapas

Para obter mais exemplos de resolvedor, consulte: