Mutações

Esta é a parte 3 da série para GraphQL e Adobe Commerce. Mutações são a capacidade de salvar, atualizar e retornar valores usando o GraphQL.

Vídeos e tutoriais relacionados ao GraphQL nesta série

Exemplo de mutação

Qualquer especificação completa da API precisa oferecer a capacidade não apenas de consultar dados, mas também de criá-los e atualizá-los.

REST distingue entre solicitações que alteram dados e aquelas que não têm o tipo de solicitação ou "verbo" (GET vs. POST ou PUT).
Ao usar o GraphQL, as consultas de modificação de dados são diferenciadas pela palavra-chave mutation que corresponde a uma
tipo raiz no esquema definido no servidor.

Observe este exemplo de mutação para adicionar um produto ao carrinho de um usuário. (Isso requer uma ID de carrinho gerada
para a sessão do cliente conectado ou usando a mutação createEmptyCart.)

mutation doAddToCart(
    $cartId: String!,
    $cartItems: [CartItemInput!]!
) {
    addProductsToCart(
        cartId: $cartId
        cartItems: $cartItems
    ) {
        cart {
            total_quantity
            prices {
                grand_total {
                    value
                }
            }
        }
    }
}

Você pode imaginar a mutação acima sendo enviada em uma solicitação junto com o seguinte dicionário de variáveis:

{
  "cartId": "{cart-id}",
  "cartItems": [
    {
      "quantity": 1,
      "sku": "VT01-RN-XS"
    }
  ]
}

E, finalmente, você pode receber uma resposta como esta:

{
  "data": {
    "addProductsToCart": {
      "cart": {
        "total_quantity": 1,
        "prices": {
          "grand_total": {
            "value": 35.2
          }
        }
      }
    }
  }
}

O principal a ser observado sobre o exemplo acima é que, além do uso da palavra-chave mutation em vez de query,
a sintaxe é idêntica a um query. Como consultas, a mutação inclui:

  • Um nome de operação arbitrário (doAddToCart)
  • Uma lista de variáveis (por exemplo, $cartId)
  • Um campo inicial (addProductsToCart) com argumentos (por exemplo, cartId, definido como o valor de $cartId) entre parênteses
  • Uma subseleção de campos entre chaves

A subseleção de campos permite definir com flexibilidade os campos que você deseja retornar (do tipo atribuído como
valor de retorno de addProductsToCart - AddProductsToCartOutput) após a conclusão da mutação.

Como explicado anteriormente, os campos definidos em um esquema do GraphQL começam em um tipo raiz para consultas (normalmente chamados de Query). Da mesma forma,
outro tipo de raiz existe para mutações (normalmente referido como Mutation). addProductsToCart é um campo
nesse tipo de raiz.

Algumas outras observações sobre o exemplo acima:

  • O caractere ! com os sufixos String e CartItemInput indica que a variável é obrigatória.
  • Os colchetes ([]) ao redor do tipo CartItemInput especificado para $cartItems indicam uma lista
    desse tipo em vez de um valor único.

Recursos úteis do GraphQL

recommendation-more-help
3a5f7e19-f383-4af8-8983-d01154c1402f