Inventory

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

As APIs de Inventory do PlayFab oferecem a capacidade de gerenciar e armazenar os inventários dos seus jogadores e os dados de inventário. Recursos como Pilhas e Coleções oferecem flexibilidade na estruturação dos inventários dos jogadores e permitem que esse sistema funcione com qualquer jogo

Gerenciando inventários de jogadores

As APIs a seguir são usadas para ajudar a adicionar, remover, atualizar e excluir itens no inventário de um jogador. O limite atual é de 10000 itens, e você receberá um erro se ultrapassar esse valor.

Obtendo o inventário de um jogador

Game Manager

No Game Manager, navegue até Players
Selecione o jogador que você deseja visualizar ou crie um New Player e, em seguida, vá para Inventory (V2)

API

Você pode usar a GetInventoryItems para obter o inventário do jogador. Os jogadores estão limitados a acessar e manipular apenas o próprio inventário. Entidades de título podem passar um parâmetro Entity para indicar qual inventário de jogador desejam acessar. Um exemplo de solicitação GetInventoryItems:

{
  "Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
  },
  "CollectionId": "main_character",
  "Count": 15,
  "ContinuationToken": "abc="
}

Mais informações sobre como usar CollectionId e ter vários inventários por jogador podem ser encontradas aqui.

Tokens de continuação

O campo ContinuationToken retornado por uma resposta de pesquisa pode ser passado para uma solicitação de inventário para paginar por várias contagens de resultados.

Adicionar itens de inventário

A API AddInventoryItems é usada para adicionar itens diretamente ao inventário de um jogador específico. Ela recebe os parâmetros EntityId, ItemId e Amount e adiciona o item fornecido ao inventário de um jogador Um exemplo de solicitação AddInventoryItems:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

Subtrair itens de inventário

A API SubtractInventoryItems é usada para reduzir diretamente um item no inventário de um jogador em uma quantidade específica. Ela recebe os parâmetros EntityId, ItemId e Amount e remove a quantidade fornecida do item. Essa API gerará um erro se você tentar remover mais do que a quantidade disponível no momento. Um exemplo de solicitação SubtractInventoryItems:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}

Atualizar itens de inventário

A API UpdateInventoryItems é usada para definir diretamente um item no inventário de um jogador com uma quantidade específica. Ela recebe os parâmetros EntityId, ItemId e Amount e define a quantidade fornecida do item. Essa API pode ser usada tanto para aumentar quanto para reduzir a quantidade de um item, além de adicionar itens ao inventário de um jogador caso o item não exista. Um exemplo de solicitação UpdateInventoryItems:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "Amount": 10
    }
}

Excluir itens de inventário

A API DeleteInventoryItems é usada para excluir uma pilha inteira de itens do inventário de um jogador. Um exemplo de solicitação DeleteInventoryItems:

{
   "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
}

Comprar itens de inventário

A API PurchaseInventoryItems usa o preço do item definido no catálogo, deduz o custo do inventário do jogador e o troca pela quantidade desejada do item. Você deve especificar o Item que deseja comprar e a Amount do item que deseja comprar. Há alguns parâmetros principais específicos da API PurchaseInventoryItems:

PriceAmounts é uma lista de itens e quantidades que são preços por item do item. Esses preços devem corresponder a um valor configurado no Catálogo ou na Loja especificada.
StoreId é um parâmetro opcional da Loja da qual o item será comprado. Mais informações sobre Lojas podem ser encontradas aqui

Um exemplo de solicitação PurchaseInventoryItems:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
}

A API PurchaseInventoryItems é usada para compras com moedas virtuais. Para compras com dinheiro real por meio de marketplaces externos (Apple App Store, Google Play, Steam, Microsoft Store), use as APIs de resgate correspondentes (como RedeemAppleAppStoreInventoryItems, RedeemGooglePlayInventoryItems, RedeemSteamInventoryItems ou RedeemMicrosoftStoreInventoryItems). Essas APIs validam o recibo de compra com o marketplace e concedem os itens ao inventário do jogador. Para obter mais informações, consulte Resgate no marketplace.

Pacotes

Quando um pacote é comprado (via PurchaseInventoryItems ou uma API de resgate de marketplace), o pacote é desempacotado automaticamente no inventário do jogador. Os itens individuais referenciados em ItemReferences do pacote são concedidos diretamente; o pacote em si não aparece como um item no inventário do jogador. Por exemplo, comprar um pacote contendo 2x Laser Sword e 2x Laser Gun concede esses itens individualmente. O custo em moeda virtual definido em PriceOptions do pacote é deduzido do inventário do jogador como parte da transação. Pacotes vinculados a produtos de marketplace via AlternateIds seguem o mesmo comportamento de desempacotamento quando resgatados. Para obter mais informações sobre como criar pacotes, consulte Pacotes.

Transferir itens de inventário

A API TransferInventoryItems pode ser usada de três maneiras diferentes.

Para transferir itens entre jogadores (por exemplo, o Jogador A dá três maçãs ao Jogador B)
Para transferir itens entre as coleções de inventário de um único jogador (por exemplo, o Jogador A move sua espada longa do inventário do personagem Mago para o inventário do personagem Guerreiro)
Para transferir itens dentro do inventário de um único jogador para criar, remover e manipular Pilhas de itens (por exemplo, o Jogador A divide sua Pilha de 10 moedas de ouro em duas pilhas de três e sete moedas de ouro)

Os parâmetros GivingItem e Amount são usados para representar a quantidade e o item que está sendo transferido. O ReceivingItem representa o destino do item na conta do jogador que recebe. Os parâmetros GivingItem e ReceivingItem são objetos InventoryItemReference que contêm o Id do item e o StackId. Tanto GivingItem quanto ReceivingItem podem estar vazios para lidar com transferências em que uma entidade não está transferindo itens. A menos que especificado, todos os itens são definidos como default para o StackId quando adicionados/transferidos para o inventário de um jogador.

1. Transferência entre jogadores

Para uma transferência entre jogadores, GivingEntity e ReceivingEntity devem ser especificados, representando o jogador que transfere os itens e o jogador que recebe os itens, respectivamente. Um exemplo de solicitação TransferInventoryItems entre jogadores:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "DEFG98765432"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 1
}

2. Transferência entre coleções

Para uma transferência entre coleções, GivingCollectionId e ReceivingCollectionId devem ser definidos, representando a ID da coleção de inventário de origem e de destino da transferência, respectivamente. Um exemplo de solicitação TransferInventoryItems entre coleções:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingCollectionId": "default",
    "ReceivingCollectionId": "main_character",
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10
}

A solicitação acima transfere 10 unidades do item da coleção default do jogador para a coleção main_character. Mais informações sobre coleções podem ser encontradas aqui.

3. Transferência entre pilhas

Para uma transferência entre pilhas, o StackId de GivingItem e de ReceivingItem da solicitação deve ser especificado. Um exemplo de solicitação TransferInventoryItems entre pilhas:

{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "default",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "MyNewStack",
    },
    "Amount": 10
}

A solicitação acima transfere 10 unidades do item da pilha default do jogador para a pilha MyNewStack. Mais informações sobre pilhas podem ser encontradas aqui.

API ExecuteInventoryOperations

Você pode usar a API ExecuteInventoryOperations para agrupar várias operações de inventário em uma única solicitação. As operações ocorrem na ordem especificada na solicitação e, se uma operação não puder ser executada, todo o conjunto de operações será cancelado. A ExecuteInventoryOperations recebe um parâmetro Operation que é uma lista de operações. Pode haver no máximo 50 operações na lista Operation, mas os tipos de operação podem se repetir (por exemplo, 10 operações Add são válidas). Também há um limite de 300 itens que podem ser modificados/adicionados em uma única solicitação. Por exemplo, adicionar um pacote com 50 itens conta como 50 itens modificados. Os tipos de operação válidos são:

Add
Subtract
Update
Purchase
Transfer*
Delete

*Somente transferências em uma única coleção são compatíveis dentro de um lote.

Um exemplo de solicitação ExecuteInventoryOperations:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Operations": [
        {
            "Update": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                    "Amount": 10
                }
            }
        },
        {
            "Subtract": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                },
                "Amount": 5
            }
        }
    ]
}

Idempotência

Ao chamar as APIs de Inventory, você pode passar uma IdempotencyId que pode ser usada em situações em que chamadas repetitivas estão sendo feitas para fins de fallback ou redundância. Se várias chamadas de API tiverem a mesma IdempotencyId, o sistema garantirá que apenas uma dessas solicitações seja processada. Por exemplo, a seguinte solicitação de API PurchaseItem pode ser chamada várias vezes, mas como todas as solicitações têm a mesma IdempotencyId, apenas uma única compra será feita para o inventário desse jogador.

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
    "IdempotencyId": "ABC123"
}

As IdempotencyId são armazenadas e aplicadas por 14 dias; depois disso, a ID pode ser usada novamente.

Usar a mesma IdempotencyId para tipos de solicitação diferentes causará um conflito e gerará um erro.

ETags e controle de simultaneidade

As APIs de gravação de inventário oferecem suporte ao controle de simultaneidade otimista por meio de ETags e cabeçalhos HTTP. Para obter todos os detalhes, consulte ETags de inventário.

Propriedades de exibição

As Propriedades de exibição são propriedades de item personalizadas que podem ser adicionadas a itens e pilhas de itens nos inventários dos jogadores. Essas propriedades podem ser adicionadas pelas operações AddInventoryItems, PurchaseInventoryItems, TransferInventoryItems e UpdateInventoryItems.

Adicionando propriedades a novas pilhas/itens

Para as APIs AddInventoryItems, PurchaseInventoryItems e TransferInventoryItems, as Propriedades de exibição só podem ser adicionadas quando uma nova pilha é criada. Para definir Propriedades de exibição para novos itens, o parâmetro NewStackValues deve ser definido na solicitação de API. Um exemplo de solicitação AddInventoryItems com NewStackValues:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack"
    },
    "Amount": 15,
    "NewStackValues": {
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": true,
            "Rarity": "Legendary"
        }
    }
}

Mais informações sobre pilhas podem ser encontradas aqui.

Atualizando propriedades de pilhas/itens existentes

Para atualizar as Propriedades de exibição em itens existentes, a API UpdateInventoryItems pode ser usada para modificar as propriedades diretamente. Um exemplo de solicitação UpdateInventoryItems com DisplayProperties:

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack",
        "Amount": 15,
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": false,
            "Rarity": "Epic"
        }
    }
}

​Inventory

​Gerenciando inventários de jogadores

​Obtendo o inventário de um jogador

​Game Manager

​API

Tokens de continuação

​Adicionar itens de inventário

​Subtrair itens de inventário

​Atualizar itens de inventário

​Excluir itens de inventário

​Comprar itens de inventário

​Pacotes

​Transferir itens de inventário

​1. Transferência entre jogadores

​2. Transferência entre coleções

​3. Transferência entre pilhas

​API ExecuteInventoryOperations

​Idempotência

​ETags e controle de simultaneidade

​Propriedades de exibição

​Adicionando propriedades a novas pilhas/itens

​Atualizando propriedades de pilhas/itens existentes

Inventory

Gerenciando inventários de jogadores

Obtendo o inventário de um jogador

Game Manager

API

Adicionar itens de inventário

Subtrair itens de inventário

Atualizar itens de inventário

Excluir itens de inventário

Comprar itens de inventário

Pacotes

Transferir itens de inventário

1. Transferência entre jogadores

2. Transferência entre coleções

3. Transferência entre pilhas

API ExecuteInventoryOperations

Idempotência

ETags e controle de simultaneidade

Propriedades de exibição

Adicionando propriedades a novas pilhas/itens

Atualizando propriedades de pilhas/itens existentes