Transações idempotentes e padrões de repetição no Economy v2

O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o Fórum do PlayFab.

Falhas de rede, tempos limite e solicitações duplicadas são inevitáveis em jogos ao vivo. O Economy v2 fornece o IdempotencyId para evitar transações duplicadas. Esse recurso garante que uma operação seja processada apenas uma vez, mesmo que a mesma solicitação seja enviada várias vezes. Para controle de simultaneidade otimista (garantir que uma gravação só seja bem-sucedida se o inventário não tiver sido alterado desde a sua última leitura), consulte ETags e controle de simultaneidade.

Pré-requisitos

Uma conta de desenvolvedor do PlayFab.
Um título criado no Game Manager.
Pelo menos um item de catálogo publicado e uma moeda virtual.

Como funciona

Quando você inclui um IdempotencyId em uma solicitação de gravação de inventário, o PlayFab armazena esse ID por 14 dias. Se outra solicitação chegar com o mesmo IdempotencyId, o PlayFab retornará o resultado da solicitação original sem processar a operação novamente.

APIs compatíveis

O IdempotencyId é compatível com todas as APIs de gravação de inventário:

Exemplo: compra segura com repetição

Neste cenário, um jogador compra uma Espada Laser. O cliente gera um IdempotencyId exclusivo (por exemplo, um GUID) antes de enviar a solicitação:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "{{PlayerID}}"
    },
    "Item": {
        "Id": "{{LaserSwordID}}"
    },
    "Amount": 1,
    "PriceAmounts": [
        {
            "ItemId": "{{DiamondCurrencyID}}",
            "Amount": 5
        }
    ],
    "IdempotencyId": "b7e3f1a2-9c4d-4e8f-a1b2-3c4d5e6f7a8b"
}

Se o cliente não receber uma resposta (por exemplo, por tempo limite de rede), ele poderá repetir com segurança exatamente a mesma solicitação com o mesmo IdempotencyId. O PlayFab reconhece a duplicata e retorna o resultado original. O jogador é cobrado apenas uma vez.

Práticas recomendadas

Gere um ID exclusivo por operação lógica: use um GUID ou UUID. Não reutilize o mesmo ID para operações diferentes.
Gere o ID no lado do cliente antes da primeira tentativa: essa prática garante que todas as repetições usem o mesmo ID.
Não altere o corpo da solicitação entre as repetições: usar o mesmo IdempotencyId com um corpo de solicitação diferente causa um erro de conflito.
Os IDs expiram após 14 dias: depois disso, o mesmo ID pode ser usado novamente para uma nova operação.

As APIs de resgate são automaticamente idempotentes

As APIs de resgate de marketplace (RedeemAppleAppStoreInventoryItems, RedeemGooglePlayInventoryItems, RedeemMicrosoftStoreInventoryItems, RedeemSteamInventoryItems) não exigem um IdempotencyId. Elas são inerentemente idempotentes. Cada recibo ou token de marketplace só pode ser resgatado uma vez. Uma segunda chamada com o mesmo recibo retorna sucesso, mas não concede nada.

Cenários comuns

Cenário	Abordagem recomendada
Compra no lado do cliente (o jogador compra um item)	Gere um GUID antes da primeira tentativa e repita com o mesmo ID em caso de tempo limite.
Concessão de recompensa no lado do servidor (conclusão de missão)	Use um ID determinístico derivado da missão e do jogador (por exemplo, `questId-playerId`) para evitar concessões em dobro.
Resgate de marketplace	Nenhum `IdempotencyId` necessário: as APIs de resgate são automaticamente idempotentes.

XBOX Services

PlayFab

Transações idempotentes e padrões de repetição no Economy v2

Pré-requisitos

Como funciona

APIs compatíveis

Exemplo: compra segura com repetição

Práticas recomendadas

As APIs de resgate são automaticamente idempotentes

Cenários comuns

Confira também

​Pré-requisitos

​Como funciona

​APIs compatíveis

​Exemplo: compra segura com repetição

​Práticas recomendadas

​As APIs de resgate são automaticamente idempotentes

​Cenários comuns

​Confira também

Pré-requisitos

Como funciona

APIs compatíveis

Exemplo: compra segura com repetição

Práticas recomendadas

As APIs de resgate são automaticamente idempotentes

Cenários comuns

Confira também