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 pelo mutation que corresponde a um tipo de raiz diferente 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 conectada ou usando o createEmptyCart mutação.)

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 ponto a ser observado sobre o exemplo acima é que, além do uso do mutation palavra-chave 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, defina 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 o 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, existe outro tipo de raiz para mutações (normalmente referido como Mutation). addProductsToCart é um campo nesse tipo de raiz.

Algumas outras observações sobre o exemplo acima:

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

Recursos úteis do GraphQL

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