GUIA

Global IDs

Como funcionam os IDs globais Relay na Storefront API.

Visão Geral

Todos os objetos da API que possuem um campo id usam IDs globais Relay. Cada ID é uma string base64 que codifica o tipo do objeto e seu identificador interno.

Formato

Um Global ID é uma string base64 no formato Tipo:uuid. Por exemplo:

Global ID (base64)DecodificadoTipo
UHJvZHVjdDphYmMxMjM=Product:abc123Product
T3JkZXI6ZGVmNDU2Order:def456Order
Q2F0ZWdvcnk6Z2hpNzg5Category:ghi789Category

Por que Global IDs?

  • Unicidade global: Cada ID é único em toda a API, independente do tipo
  • Tipo embutido: O servidor sabe qual tipo de objeto buscar a partir do ID
  • Cache: Clients GraphQL (como Apollo, Relay) usam o ID para normalização de cache

Buscando por ID

Use a query product para buscar um produto pelo seu Global ID, ou products para buscar múltiplos.

Decodificação

Para decodificar um Global ID no frontend:

Importante: Global IDs são opacos. Não decodifique o ID para extrair o UUID interno em produção — use as queries da API para buscar objetos. A decodificação é útil apenas para debugging.

Decodificar Global ID

JavaScript
// Apenas para debugging
const globalId = "UHJvZHVjdDphYmMxMjM=";
const decoded = atob(globalId);
console.log(decoded);
// → "Product:abc123"

const [type, id] = decoded.split(":");
console.log(type); // "Product"
console.log(id);   // "abc123"

Buscar por Global ID

GraphQL
query GetProduct($id: ID!) {
  product(id: $id) {
    id
    title
    price
    images { url }
  }
}

Buscar Múltiplos

GraphQL
query GetProducts($ids: [ID!]!) {
  products(ids: $ids) {
    id
    title
    price
  }
}

Variáveis

JSON
{
  "id": "UHJvZHVjdDphYmMxMjM=",
  "ids": [
    "UHJvZHVjdDphYmMxMjM=",
    "UHJvZHVjdDpkZWY0NTY="
  ]
}