Explorar APIs GraphQL

A API GraphQL do AEM fornece uma linguagem de consulta avançada para expor os dados dos Fragmentos de conteúdo aos aplicativos de downstream. Os modelos de Fragmento de conteúdo definem o schema de dados usado pelos Fragmentos de conteúdo. Sempre que um Modelo de fragmento de conteúdo é criado ou atualizado, o esquema é traduzido e adicionado ao "gráfico" que compõe a API GraphQL.

Neste capítulo, exploraremos algumas consultas GraphQL comuns para coletar conteúdo usando um IDE chamado GraphiQL. O GraphiQL IDE permite testar e refinar rapidamente as consultas e os dados retornados. O GraphiQL também oferece acesso fácil à documentação, facilitando o aprendizado e a compreensão de quais métodos estão disponíveis.

Pré-requisitos

Este é um tutorial de várias partes e presume-se que as etapas descritas em Criação de fragmentos de conteúdo foram concluídas.

Objetivos

  • Saiba como usar a ferramenta GraphiQL para criar uma consulta usando a sintaxe GraphQL.
  • Saiba como consultar uma lista de Fragmentos de conteúdo e um único Fragmento de conteúdo.
  • Saiba como filtrar e solicitar atributos de dados específicos.
  • Saiba como consultar uma variação de um Fragmento de conteúdo.
  • Saiba como associar-se a uma consulta de vários modelos de Fragmento de conteúdo

Instalação da ferramenta GraphiQL

O GraphiQL IDE é uma ferramenta de desenvolvimento e é necessário apenas em ambientes de nível inferior, como uma instância de desenvolvimento ou local. Por conseguinte, não está incluído no projeto de AEM, mas constitui um pacote separado que pode ser instalado numa base ad hoc.

  1. Navegue até o Portal de distribuição de software > AEM como um Cloud Service.

  2. Procure por "GraphiQL" (certifique-se de incluir o i em GraphiQL.

  3. Baixe o Pacote de Conteúdo GraphiQL v.x.x mais recente

    Download do pacote GraphiQL

    O arquivo zip é um pacote AEM que pode ser instalado diretamente.

  4. No menu AEM Iniciar, navegue até Ferramentas > Implantação > Pacotes.

  5. Clique em Upload Package e escolha o pacote baixado na etapa anterior. Clique em Install para instalar o pacote.

    Instalar o pacote GraphiQL

Consultar uma lista de fragmentos de conteúdo

Um requisito comum será consultar vários Fragmentos de conteúdo.

  1. Navegue até o GraphiQL IDE em http://localhost:4502/content/graphiql.html.

  2. Cole o seguinte query no painel esquerdo (abaixo da lista de comentários):

    {
      contributorList {
        items {
            _path
          }
      }
    }
    
  3. Pressione o botão Play no menu superior para executar a consulta. Você deve ver os resultados dos fragmentos de conteúdo dos Contribuidores do capítulo anterior:

    Resultados da lista de colaboradores

  4. Posicione o cursor abaixo do texto _path e insira CTRL+Space para acionar a dica de código. Adicione fullName e occupation à query.

    Atualizar consulta com hitação de código

  5. Execute a consulta novamente pressionando o botão Play e você deverá ver que os resultados incluem as propriedades adicionais de fullName e occupation.

    Nome completo e resultados da atividade profissional

    fullName e occupation são propriedades simples. Lembre-se do capítulo Definindo Modelos de Fragmento de Conteúdo de que fullName e occupation são os valores usados ao definir o Nome da Propriedade dos respectivos campos.

  6. pictureReference e biographyText representam campos mais complexos. Atualize a consulta com o seguinte para retornar dados sobre os campos pictureReference e biographyText.

    {
    contributorList {
        items {
          _path
          fullName
          occupation
          biographyText {
            html
          }
          pictureReference {
            ... on ImageRef {
                _path
                width
                height
                }
            }
        }
      }
    }
    

    biographyText é um campo de texto de várias linhas e a API GraphQL permite escolher diversos formatos para os resultados, como html, markdownou json plaintext.

    pictureReference é uma referência de conteúdo e deve ser uma imagem, portanto, ImageRef o objeto incorporado é usado. Isso nos permite solicitar dados adicionais sobre a imagem que está sendo referenciada, como width e height.

  7. Em seguida, experimente consultar uma lista de Aventuras. Execute a seguinte consulta:

    {
      adventureList {
        items {
          adventureTitle
          adventureType
          adventurePrimaryImage {
            ...on ImageRef {
              _path
              mimeType
            }
          }
        }
      }
    }
    

    Você deve ver uma lista de Adventures retornada. Você pode experimentar adicionando campos adicionais ao query.

Filtrar uma lista de fragmentos de conteúdo

Em seguida, vamos examinar como é possível filtrar os resultados para um subconjunto de Fragmentos de conteúdo com base em um valor de propriedade.

  1. Insira a seguinte query na interface do usuário GraphiQL:

    {
    contributorList(filter: {
      occupation: {
        _expressions: {
          value: "Photographer"
          }
        }
      }) {
        items {
          _path
          fullName
          occupation
        }
      }
    }
    

    A consulta acima realiza uma pesquisa em relação a todos os contribuidores no sistema. O filtro adicionado ao início da consulta executará uma comparação no campo occupation e na string "Fotógrafo".

  2. Execute a query, espera-se que apenas um único Contributor seja retornado.

  3. Insira a seguinte query para consultar uma lista de Aventuras onde adventureActivity é não igual a "Surfing":

    {
      adventureList(filter: {
        adventureActivity: {
            _expressions: {
                _operator: EQUALS_NOT
                value: "Surfing"
            }
        }
    }) {
        items {
        _path
        adventureTitle
        adventureActivity
        }
      }
    }
    
  4. Execute a consulta e inspecione os resultados. Observe que nenhum dos resultados inclui um adventureType igual a "Navegação".

Há muitas outras opções para filtrar e criar consultas complexas, acima estão apenas alguns exemplos.

Consultar um único fragmento de conteúdo

Também é possível consultar diretamente um único Fragmento de conteúdo. O conteúdo no AEM é armazenado de maneira hierárquica e o identificador exclusivo de um fragmento é baseado no caminho do fragmento. Se o objetivo for retornar dados sobre um único fragmento, é preferível usar o caminho e consultar o modelo diretamente. Usar essa sintaxe significa que a complexidade da consulta será muito baixa e gerará um resultado mais rápido.

  1. Insira a seguinte query no editor GraphiQL:

    {
     contributorByPath(_path: "/content/dam/wknd/en/contributors/stacey-roswells") {
        item {
          _path
          fullName
          biographyText {
            html
          }
        }
      }
    }
    
  2. Execute a query e observe que o único resultado do fragmento Stacey Roswells é retornado.

    No exercício anterior, você usou um filtro para restringir uma lista de resultados. Você pode usar uma sintaxe semelhante para filtrar por caminho, no entanto, a sintaxe acima é preferida por motivos de desempenho.

  3. Lembre-se no capítulo Criação de fragmentos de conteúdo de que uma variação Resumo foi criada para Stacey Roswells. Atualize a consulta para retornar a variação Summary:

    {
    contributorByPath
    (
        _path: "/content/dam/wknd/en/contributors/stacey-roswells"
        variation: "summary"
    ) {
        item {
          _path
          fullName
          biographyText {
            html
          }
        }
      }
    }
    

    Mesmo que a variação tenha sido nomeada como Summary, as variações são persistentes em minúsculas e, portanto, summary é usada.

  4. Execute a query e observe que o campo biography contém um resultado html muito mais curto.

Consulta para vários modelos de fragmento de conteúdo

Também é possível combinar consultas separadas em um único query. Isso é útil para minimizar o número de solicitações HTTP necessárias para potencializar o aplicativo. Por exemplo, a visualização Início de um aplicativo pode exibir conteúdo com base em dois Modelos de Fragmento de Conteúdo diferentes. Em vez de executar dois consultas separadas, podemos combinar as consultas em uma única solicitação.

  1. Insira a seguinte query no editor GraphiQL:

    {
      adventureList {
        items {
          _path
          adventureTitle
        }
      }
      contributorList {
        items {
          _path
          fullName
        }
      }
    }
    
  2. Execute a query e observe que o conjunto de resultados contém dados de Adventures e Contributors:

{
  "data": {
    "adventureList": {
      "items": [
        {
          "_path": "/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp",
          "adventureTitle": "Bali Surf Camp"
        },
        {
          "_path": "/content/dam/wknd/en/adventures/beervana-portland/beervana-in-portland",
          "adventureTitle": "Beervana in Portland"
        },
        ...
      ]
    },
    "contributorList": {
      "items": [
        {
          "_path": "/content/dam/wknd/en/contributors/jacob-wester",
          "fullName": "Jacob Wester"
        },
        {
          "_path": "/content/dam/wknd/en/contributors/stacey-roswells",
          "fullName": "Stacey Roswells"
        }
      ]
    }
  }
}

Recursos adicionais

Para obter mais exemplos de consultas GraphQL, consulte: Saiba como usar GraphQL com AEM - Conteúdo de amostra e Consultas.

Parabéns!

Parabéns, você acabou de criar e executar várias consultas GraphQL!

Próximas etapas

No próximo capítulo, Consultando AEM de um aplicativo React, você explorará como um aplicativo externo pode consultar AEM pontos de extremidade GraphQL. O aplicativo externo que modifica o aplicativo WKND GraphQL React para adicionar consultas GraphQL de filtragem, permitindo que o usuário do aplicativo filtre aventuras por atividade. Você também será apresentado a algum tratamento básico de erros.

Nesta página