Olá, turma! Sejam muito bem-vindos à nossa Aula 74 do curso “Shopify do Zero ao Avançado”! 👋

Chegamos a um ponto crucial e extremamente poderoso do nosso desenvolvimento em Shopify: a GraphQL Admin API. Se você já estava impressionado com a flexibilidade do Liquid ou com as possibilidades da REST Admin API, prepare-se, pois o GraphQL vai levar suas habilidades para outro nível, permitindo interações muito mais eficientes e complexas com os dados da sua loja! 🚀

Nesta aula, vamos mergulhar fundo no universo do GraphQL, entender suas vantagens e aprender a construir consultas e mutações avançadas para gerenciar sua loja de formas que antes pareciam impossíveis. Vamos lá?

—

Aula 74 – Loja Shopify do Zero ao Avançado: GraphQL Admin API para consultas avançadas

📚 O que você vai aprender nesta aula

Ao final desta aula, você será capaz de:

• Diferenciar a GraphQL Admin API da REST Admin API e da Storefront API, entendendo seus respectivos casos de uso.
• Compreender a arquitetura e os princípios do GraphQL (campos, argumentos, fragments, etc.).
• Configurar um Custom App no Shopify para obter credenciais de acesso à GraphQL Admin API.
• Construir e executar queries (consultas) GraphQL avançadas para buscar dados específicos da sua loja.
• Implementar paginação baseada em cursor para lidar com grandes volumes de dados de forma eficiente.
• Realizar mutações (operações de escrita) para criar, atualizar ou deletar recursos da sua loja.
• Utilizar variáveis e fragments para tornar suas consultas mais dinâmicas e reutilizáveis.
• Utilizar ferramentas como o GraphQL Admin API Explorer e Postman/Insomnia para testar suas requisições.

🔗 Conectando com aulas anteriores

Nas aulas anteriores, exploramos diversas formas de interagir com o Shopify. Começamos com a personalização visual da loja usando Liquid, HTML, CSS e JavaScript diretamente no tema. Em aulas mais avançadas, introduzimos o conceito de APIs ao usar a Storefront API (para dados públicos no frontend) e, provavelmente, a REST Admin API (para interações mais administrativas através de Custom Apps ou Private Apps).

Relembramos que, enquanto o Liquid é ótimo para renderizar dados estáticos ou pré-definidos no tema, e a Storefront API é excelente para buscar dados públicos sem autenticação para experiências dinâmicas no cliente, para operações administrativas que exigem leitura/escrita de dados sensíveis da loja (produtos, pedidos, clientes, etc.), precisamos de uma API autenticada. A REST Admin API foi uma introdução a isso, permitindo-nos buscar e manipular dados de forma mais tradicional, com múltiplos endpoints e estruturas de resposta fixas.

Agora, na Aula 74, damos um salto para o futuro das APIs com a GraphQL Admin API. Ela resolve muitas das dores da REST, oferecendo uma forma muito mais flexível, eficiente e poderosa de gerenciar os dados da sua loja, especialmente quando você precisa de dados complexos ou quer minimizar o número de requisições. Pense na GraphQL como uma evolução que lhe dará controle total sobre o que você busca e como você busca! 💡

📖 Conteúdo Principal

O que é GraphQL? Por que usá-lo no Shopify?

GraphQL é uma linguagem de consulta para APIs e um runtime para executar essas consultas em cima dos seus dados. Desenvolvido pelo Facebook, ele oferece uma alternativa poderosa e flexível ao REST.

Vantagens do GraphQL no Shopify:

1. Flexibilidade: Em vez de múltiplos endpoints com estruturas de dados fixas (como no REST), o GraphQL possui um único endpoint. Você envia uma query que especifica exatamente os dados que precisa, e o servidor responde com apenas esses dados. Isso evita o “over-fetching” (pegar mais dados do que o necessário) e o “under-fetching” (pegar menos dados do que o necessário, exigindo múltiplas requisições).

2. Eficiência: Menos dados transferidos, menos requisições. Isso é crucial para performance, especialmente em aplicações móveis ou com grande volume de dados.

3. Tipagem Forte: O GraphQL tem um sistema de tipos robusto, o que significa que você sabe exatamente quais dados estão disponíveis e em que formato. Isso facilita o desenvolvimento e reduz erros.

4. Auto-Documentação: Devido ao sistema de tipos, as APIs GraphQL são inerentemente auto-documentadas. Você pode “explorar” o schema para descobrir todas as operações e campos disponíveis.

5. Evolução Simplificada: Adicionar novos campos ou funcionalidades é mais fácil, pois os clientes controlam o que recebem.

GraphQL Admin API vs. Storefront API vs. REST Admin API

É fundamental entender a diferença e o propósito de cada API do Shopify:

• Storefront API (GraphQL):

Propósito: Acessar dados públicos da loja (produtos, coleções, blog posts, etc.) no frontend* (diretamente do navegador ou app mobile).

• Autenticação: Geralmente usa um Storefront Access Token público, sem informações sensíveis.

Uso: Experiências de compra personalizadas, PWA (Progressive Web Apps), aplicações headless*.

Já cobrimos isso em aulas anteriores.*

• REST Admin API (HTTP/JSON):

Propósito: Realizar operações administrativas (criar produtos, atualizar pedidos, gerenciar clientes) no backend* da sua aplicação.

• Autenticação: Requer um Access Token gerado por um Custom App ou app público, que confere permissões específicas (scopes).
• Uso: Integrações com ERPs, CRMs, ferramentas de marketing, apps customizados.

Provavelmente abordado em aulas anteriores como uma introdução a APIs administrativas.*

• GraphQL Admin API (HTTP/GraphQL):

Propósito: Idem à REST Admin API, mas com a flexibilidade e eficiência do GraphQL. Ideal para operações administrativas complexas e manipulação detalhada de dados no backend* da sua aplicação.

• Autenticação: Também requer um Access Token de um Custom App ou app público, com as mesmas permissões (scopes) da REST Admin API.
• Uso: Criação de apps Shopify robustos, dashboards personalizados, ferramentas de automação que exigem controle fino sobre os dados.
• O FOCO DA NOSSA AULA DE HOJE! 🤩

Em resumo: Se você precisa de dados públicos para o seu frontend, use a Storefront API. Se você precisa fazer operações administrativas simples ou se sente mais confortável com REST, use a REST Admin API. Mas se você precisa de controle máximo, eficiência e flexibilidade para operações administrativas complexas e futuras escalabilidades, a GraphQL Admin API é o caminho!

Autenticação: Criando um Custom App para Acesso

Para interagir com a GraphQL Admin API, você precisa de um token de acesso que confira as permissões necessárias. A forma mais comum para desenvolvimento e testes é através de um Custom App.

1. Acesse o Admin Shopify: Vá em Apps > Develop apps (ou Desenvolver apps).

2. Crie um Custom App: Clique em Create an app (ou Criar um app). Dê um nome, como “Meu App GraphQL”.

3. Configure Scopes (Permissões):

• Após criar o app, clique em Configure Admin API scopes.
• Aqui você define o que seu app poderá fazer. Por exemplo, para ler e escrever produtos, marque read_products e write_products. Para metafields, read_products e write_products são geralmente suficientes, ou read_all_metafields e write_all_metafields para acesso mais amplo.

Dica: Conceda apenas* as permissões que seu app realmente precisa para segurança.

4. Instale o App e Gere o Access Token:

• Vá para a seção API credentials e clique em Install app.
• Após a instalação, um Admin API access token será gerado. Este token é SECRETO e só será exibido uma vez. Copie-o e guarde-o em um local seguro (variáveis de ambiente, gerenciador de segredos). Nunca o exponha no frontend!

Captura de tela imaginária: Imagine uma screenshot da tela de criação de um Custom App, com a seção de “API credentials” destacada, mostrando o Admin API access token e o botão “Reveal token”. Em seguida, uma seta apontando para a seção “Admin API integration” e as caixas de seleção para os scopes, como read_products, write_products.

Estrutura Básica de uma Query GraphQL

Uma query GraphQL é como pedir exatamente o que você quer de um banco de dados.

• Endpoint: Para a GraphQL Admin API, o endpoint é geralmente https://{seu-dominio}.myshopify.com/admin/api/2023-10/graphql.json (substitua 2023-10 pela versão da API que deseja usar, por exemplo, 2024-01).
• Método HTTP: POST.
• Headers: X-Shopify-Access-Token: {seu-access-token} e Content-Type: application/json.
• Corpo da Requisição (JSON): Contém a query e, opcionalmente, variáveis.

Exemplo de uma query simples para buscar um produto:

graphql

query {
product(id: "gid://shopify/Product/123456789") {
id
title
handle
descriptionHtml
createdAt
}
}

No corpo da requisição JSON, isso seria:

json

{
"query": "query { product(id: "gid://shopify/Product/123456789") { id title handle descriptionHtml createdAt } }"
}

Explicação dos componentes:

• query: Indica que estamos fazendo uma consulta (leitura). Para escrita, usaríamos mutation.

product(id: "..."): O campo product é a raiz da nossa consulta, e id é um argumento* para especificar qual produto queremos. O ID deve ser o “Global ID” (GID) do Shopify. Você pode obtê-lo através da REST Admin API (/admin/api/2023-10/products/{id}.json e procurar o admin_graphql_api_id) ou outras queries GraphQL.

{ id title handle descriptionHtml createdAt }: São os campos* que queremos retornar para o produto encontrado.

Consultas Avançadas: Paginação, Filtros e Variáveis

A verdadeira força do GraphQL aparece em consultas complexas.

1. Paginação (Cursor-based)

A paginação em GraphQL é baseada em cursores, o que é mais eficiente e robusto que a paginação baseada em offset (como em REST, onde page e limit podem levar a itens duplicados ou perdidos em dados mutáveis).

• first/last: Define quantos itens você quer retornar por página.
• after/before: Define o cursor a partir do qual você quer a próxima/anterior página.
• pageInfo: Um objeto que contém informações sobre a paginação (hasNextPage, hasPreviousPage, startCursor, endCursor).

Exemplo: Listar produtos com paginação

graphql

query GetAllProductsWithPagination($numProducts: Int!, $cursor: String) {
products(first: $numProducts, after: $cursor) {
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
title
status
variants(first: 5) {
edges {
node {
id
price
sku
}
}
}
}
}
}
}

Com variáveis:

json

{
"query": "query GetAllProductsWithPagination($numProducts: Int!, $cursor: String) { products(first: $numProducts, after: $cursor) { pageInfo { hasNextPage endCursor } edges { node { id title status variants(first: 5) { edges { node { id price sku } } } } } } }",
"variables": {
"numProducts": 3,
"cursor": null
}
}

Explicação:

• $numProducts: Int!, $cursor: String: Definimos variáveis para a query. $numProducts é obrigatório (!).

products(first: $numProducts, after: $cursor): Consultamos products, pedindo numProducts itens depois* do cursor.

• edges { node { ... } }: No GraphQL, coleções de itens são frequentemente retornadas dentro de uma estrutura edges e node. node é o item em si.
• pageInfo: Essencial para saber se há mais páginas e qual o endCursor para a próxima requisição.

Para a próxima página, você usaria o endCursor da resposta atual como valor para a variável $cursor.

2. Filtros e Argumentos

Muitos campos aceitam argumentos para filtrar, ordenar ou limitar resultados.

Exemplo: Produtos de uma coleção específica

graphql

query GetCollectionProducts($collectionId: ID!) {
collection(id: $collectionId) {
id
title
products(first: 10) {
edges {
node {
id
title
priceRange {
minVariantPrice {
amount
currencyCode
}
}
}
}
}
}
}

Com variáveis:

json

{
"query": "query GetCollectionProducts($collectionId: ID!) { collection(id: $collectionId) { id title products(first: 10) { edges { node { id title priceRange { minVariantPrice { amount currencyCode } } } } } } }",
"variables": {
"collectionId": "gid://shopify/Collection/234567890"
}
}

3. Fragments

Fragments permitem que você reutilize partes de queries. Isso é útil para manter seu código DRY (Don’t Repeat Yourself) e mais legível.

Exemplo: Usando Fragments para detalhes de produto

graphql

fragment ProductDetails on Product {
id
title
handle
status
vendor
}
query GetProductsWithDetails($numProducts: Int!) {
products(first: $numProducts) {
edges {
node {
...ProductDetails # Usa o fragmento aqui
createdAt
}
}
}
}

json

{
"query": "fragment ProductDetails on Product { id title handle status vendor } query GetProductsWithDetails($numProducts: Int!) { products(first: $numProducts) { edges { node { ...ProductDetails createdAt } } } }",
"variables": {
"numProducts": 5
}
}

Mutações: Manipulando Dados

Mutações são as operações de escrita no GraphQL (criar, atualizar, deletar).

A estrutura é similar às queries, mas começam com a palavra-chave mutation.

Exemplo: Atualizar um metafield de produto

Metafields são dados personalizados que você pode anexar a produtos, clientes, pedidos, etc. São extremamente poderosos para estender a funcionalidade padrão do Shopify.

Primeiro, você precisaria saber o ownerId (o GID do produto) e o key e namespace do metafield que deseja criar/atualizar.

graphql

mutation ProductMetafieldUpdate($input: ProductMetafieldInput!) {
productUpdate(input: {
id: $input.ownerId,
metafields: [
{
id: $input.metafieldId, # Se for atualização de um metafield existente
namespace: $input.namespace,
key: $input.key,
value: $input.value,
type: $input.type
}
]
}) {
product {
id
title
metafield(namespace: $input.namespace, key: $input.key) {
id
value
}
}
userErrors {
field
message
}
}
}

Com variáveis:

json

{
"query": "mutation ProductMetafieldUpdate($input: ProductMetafieldInput!) { productUpdate(input: { id: $input.ownerId, metafields: [ { id: $input.metafieldId, namespace: $input.namespace, key: $input.key, value: $input.value, type: $input.type } ] }) { product { id title metafield(namespace: $input.namespace, key: $input.key) { id value } } userErrors { field message } } }",
"variables": {
"input": {
"ownerId": "gid://shopify/Product/123456789",
"namespace": "custom",
"key": "material_principal",
"value": "Madeira de Carvalho",
"type": "single_line_text_field",
"metafieldId": null # Use null ou omita para criar. Para atualizar, use o GID do metafield existente.
}
}
}

Dica: Ao criar um metafield pela primeira vez, você não terá um metafieldId. Deixe-o como null ou omita-o. Se você estiver atualizando um metafield existente, você precisará fornecer o metafieldId dele. Você pode buscar o metafieldId com uma query antes de fazer a mutação, caso não o tenha.

Exemplo de como buscar o ID de um metafield existente:

graphql

query GetProductMetafieldId($productId: ID!, $namespace: String!, $key: String!) {
product(id: $productId) {
id
title
metafield(namespace: $namespace, key: $key) {
id
value
type
}
}
}

Tratamento de Erros

O GraphQL retorna erros no campo errors da resposta JSON, mas também pode ter userErrors dentro do objeto da mutação para erros de validação de negócios.

json

{
"data": {
"productUpdate": {
"product": null,
"userErrors": [
{
"field": [
"input",
"metafields",
"0",
"value"
],
"message": "Value must be a valid number."
}
]
}
},
"errors": [
{
"message": "Access denied for productUpdate field. Missing access token or scopes.",
"locations": [
{
"line": 1,
"column": 1
}
],
"path": [
"productUpdate"
]
}
]
}

Sempre verifique ambos errors (erros de sintaxe ou autenticação) e userErrors (erros de lógica de negócio).

Ferramentas para Teste

1. Shopify GraphQL Admin API Explorer: A ferramenta mais fácil para começar!

• No admin Shopify, vá para Apps > Develop apps > Seu Custom App > API credentials.
• No final da página, clique em Admin API Explorer.
• Você terá um ambiente interativo para escrever queries, ver o schema, executar e ver as respostas. Perfeito para aprender e prototipar!

Captura de tela imaginária: Uma screenshot do GraphQL Admin API Explorer, mostrando o painel esquerdo para escrever a query, o painel direito para as variáveis e o painel inferior para a resposta JSON. No canto direito, um botão para explorar a documentação do schema.

2. Postman / Insomnia: Clientes HTTP robustos para gerenciar e executar requisições complexas, incluindo GraphQL.

• Configure uma requisição POST.
• URL: https://{seu-dominio}.myshopify.com/admin/api/{versao-api}/graphql.json
• Headers: X-Shopify-Access-Token e Content-Type: application/json.
• Corpo: Selecione raw e JSON, e insira o JSON contendo sua query e variables.

—

💻 Exemplos Práticos

Vamos colocar a mão na massa!

Exemplo 1: Configurando e Fazendo a Primeira Query no GraphQL Admin API Explorer

1. Crie seu Custom App: Siga os passos na seção “Autenticação” acima. Nomeie-o “Aula74-GraphQL”.

2. Defina os Scopes: Para este exemplo, garanta que read_products e write_products estejam marcados.

3. Instale o App e copie seu Admin API access token. (Não vamos usá-lo diretamente no Explorer, mas é bom ter).

4. Abra o Admin API Explorer: No seu Custom App, clique em Admin API Explorer.

• Query: Listar os 5 primeiros produtos e suas primeiras 2 variantes.

graphql

query {
products(first: 5) {
edges {
node {
id
title
status
variants(first: 2) {
edges {
node {
id
price
sku
}
}
}
}
}
}
}

• Execute a Query. Você verá uma resposta JSON detalhada com os produtos.

Captura de tela imaginária: Uma screenshot do GraphQL Admin API Explorer com a query acima no painel esquerdo e a resposta JSON formatada no painel inferior.

Exemplo 2: Query com Paginação e Variáveis

Vamos buscar produtos com paginação usando variáveis para controlar a quantidade e o cursor.

No GraphQL Admin API Explorer:

• Query:

graphql

query GetPaginatedProducts($first: Int!, $after: String) {
products(first: $first, after: $after) {
pageInfo {
hasNextPage
endCursor
}
edges {
node {
id
title
status
}
}
}
}

• Query Variables (painel inferior esquerdo):

json

{
"first": 3,
"after": null
}

• Execute. Observe os 3 primeiros produtos e o endCursor.
• Para a próxima página: Copie o endCursor da resposta, cole-o no campo after das Query Variables e execute novamente. Você verá os próximos 3 produtos.

Captura de tela imaginária: Uma sequência de duas screenshots do Explorer: a primeira mostrando a query, variáveis com after: null e a resposta; a segunda mostrando o endCursor da primeira resposta usado como after nas variáveis e a nova resposta.

Exemplo 3: Mutação para Criar/Atualizar um Metafield de Produto

Vamos criar um metafield para um produto e depois atualizá-lo.

Primeiro, precisamos de um productId (GID). Você pode pegar um de seus produtos existentes executando a query do Exemplo 1 ou buscando-o no admin (ex: gid://shopify/Product/SEU_ID_DO_PRODUTO_AQUI).

No GraphQL Admin API Explorer:

1. Mutação para Criar um Metafield:

• Mutação:

graphql

mutation CreateProductMetafield($input: ProductInput!) {
productUpdate(input: $input) {
product {
id
title
metafield(namespace: "aula74", key: "material") {
id
value
type
}
}
userErrors {
field
message
}
}
}

• Query Variables:

json

{
"input": {
"id": "gid://shopify/Product/SEU_PRODUTO_ID_AQUI",
"metafields": [
{
"namespace": "aula74",
"key": "material",
"value": "Madeira de Nogueira",
"type": "single_line_text_field"
}
]
}
}

• Execute. Se tudo der certo, você verá o produto e o novo metafield criado. Copie o id do metafield retornado! (Ex: gid://shopify/Metafield/1234567890)

2. Mutação para Atualizar o Metafield Existente:

• Mutação: A mesma mutação de antes.
• Query Variables:

json

{
"input": {
"id": "gid://shopify/Product/SEU_PRODUTO_ID_AQUI",
"metafields": [
{
"id": "gid://shopify/Metafield/SEU_METAFIEID_ID_AQUI", # O ID que você copiou
"namespace": "aula74",
"key": "material",
"value": "Metal Escovado",
"type": "single_line_text_field"
}
]
}
}

• Execute. O valor do metafield será atualizado. Você pode verificar diretamente na página do produto no admin Shopify.

Captura de tela imaginária: Uma sequência de screenshots do Explorer, primeiro criando o metafield e mostrando a resposta com o ID do metafield; segundo, atualizando o metafield usando o ID e mostrando a resposta atualizada.

—

🎯 Exercícios e Desafios

Para solidificar seu aprendizado, proponho os seguintes desafios:

1. Busca de Pedidos por Status:

• Crie uma query que liste os 5 primeiros pedidos com o status “UNFULFILLED” (não processado), retornando o id, name, createdAt e o email do cliente.
• Implemente paginação para esta query, de forma que você possa buscar os próximos 5 pedidos.

2. Atualização em Massa (conceitual):

• Imagine que você precisa atualizar o status de PUBLISHED para DRAFT para todos os produtos que possuem uma tag “liquidacao”.

Desafio: Escreva a sequência lógica* de queries e mutações GraphQL que você faria para realizar essa tarefa. (Não precisa executar de fato, apenas descrever as queries/mutações e como você as encadearia).

3. Criar um Metafield “Dimensões”:

• Para um produto de sua escolha, crie um metafield com namespace: "detalhes" e key: "dimensoes".
• O type deve ser json_string e o value deve ser um JSON válido como {"altura": "10cm", "largura": "5cm", "profundidade": "2cm"}.
• Verifique no admin se o metafield foi criado corretamente.

📝 Resumo da Aula

Nesta aula super importante, você deu um grande passo no desenvolvimento de apps Shopify ao dominar a GraphQL Admin API:

• Entendemos as vantagens do GraphQL sobre o REST para flexibilidade e eficiência, especialmente no contexto de APIs administrativas do Shopify.
• Diferenciamos a GraphQL Admin API das APIs Storefront e REST Admin.
• Aprendemos a configurar um Custom App para obter o Admin API access token, um componente de segurança crucial.
• Construímos queries GraphQL para buscar dados, utilizando campos, argumentos, e os poderosos mecanismos de paginação baseada em cursor.
• Exploramos as mutações para criar e atualizar dados, exemplificando com a manipulação de metafields de produtos.
• Vimos a importância de variáveis e fragments para queries dinâmicas e reutilizáveis.
• Conhecemos as ferramentas essenciais para prototipar e testar nossas requisições: o GraphQL Admin API Explorer e clientes HTTP como Postman/Insomnia.

Com a GraphQL Admin API, você agora tem a ferramenta mais poderosa para construir funcionalidades personalizadas e integrar sua loja Shopify a qualquer sistema externo, com total controle sobre os dados! 💪

🚀 Preparação para próxima aula

Na próxima aula, vamos levar o que aprendemos aqui para o próximo nível: vamos começar a construir um backend real (com Node.js, por exemplo) para interagir com a GraphQL Admin API. Isso nos permitirá:

• Gerenciar o Admin API access token de forma segura.
• Criar rotas personalizadas para sua aplicação.
• Integrar suas queries e mutações GraphQL em um código JavaScript real.
• Construir uma interface simples (talvez um dashboard ou ferramenta de gerenciamento) que utilize esses dados para demonstrar um aplicativo Shopify mais completo.

Prepare-se para transformar essas requisições isoladas em uma aplicação funcional!

📚 Recursos Adicionais

• Documentação Oficial da Shopify GraphQL Admin API:
• https://shopify.dev/docs/api/admin-graphql (Essencial para explorar o schema, tipos e operações disponíveis!)
• GraphQL Admin API Explorer:
• Acesse-o via seu Custom App no admin Shopify (Apps > Develop apps > seu app > API credentials > Admin API Explorer).
• Introdução ao GraphQL:
• https://graphql.org/
• Postman:
• https://www.postman.com/downloads/
• Insomnia:
• https://insomnia.rest/download/

Parabéns por chegar até aqui! A GraphQL Admin API é uma ferramenta de profissional, e dominá-la abre um leque imenso de possibilidades. Estou muito orgulhoso do seu progresso! Nos vemos na próxima aula! 👋🎓