通过

物品栏

重要

Economy v2 现已正式发布。 有关支持和反馈，请转到 PlayFab 论坛。

PlayFab 清单 API 可用于管理和存储玩家清单和清单数据。 堆栈和集合等功能可灵活地构建玩家清单，并允许此系统处理任何游戏

管理玩家清单

以下 API 用于帮助添加、删除、更新和删除玩家清单中的项目。 当前限制为 10000 个项目，如果超出此限制，将收到错误。

获取玩家清单

  1. 在游戏管理器中，导航到 Players
  2. 选择要查看或创建 New Player 的玩家，然后转到 Inventory (V2)

有关使用 CollectionId 以及每个玩家拥有多个清单的详细信息，请查看此处。

继续令牌

从搜索响应返回的 ContinuationToken 字段可以传递到清单请求中，以便通过多个结果计数进行分页。

添加清单项目。

AddInventoryItems API 用于直接将项目添加到特定玩家的清单中。 它采用 EntityId、ItemId和 Amount 参数，并将给定项添加到玩家的清单

请求 AddInventoryItems 示例：

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

减少清单项目

SubtractInventoryItems API 用于将玩家清单中的项目直接减少特定的数量。 它采用 EntityId、ItemId 和 Amount 参数，并移除指定数量的项目。 如果尝试移除的数量超过当前可用量，则此 API 将报错。

请求 SubtractInventoryItems 示例：

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

更新清单项

UpdateInventoryItems API 用于将玩家清单中的项目直接设置为特定数量。 它采用 EntityId、ItemId 和 Amount 参数，并设置指定的项目数量。 此 API 可用于增加或减少项目的数量，并在项目不存在时将其添加到玩家的清单中。

请求 UpdateInventoryItems 示例：

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

删除清单项目

DeleteInventoryItems API 用于从玩家的清单中删除整个项目堆栈。

请求 DeleteInventoryItems 示例：

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

购买清单项目

PurchaseInventoryItems API 根据目录定义的项目价格，从玩家的清单中扣除成本，与所需数量的项目进行交易。 必须指定要购买的 Item 以及要购买的项目的 Amount。

有几个特定于 PurchaseInventoryItems API 的关键参数：

  • PriceAmounts 是项目和金额的列表，即项目的单项价格。 这些价格必须与目录或指定存储中配置的值匹配。
  • StoreId 是要从中购买项目的 Store 的可选参数。 有关 Store 的详细信息，请参阅此处

请求 PurchaseInventoryItems 示例：

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

转移清单项目

TransferInventoryItems API 有三种使用方式。

  1. 对于在玩家之间转移项目（例如，玩家 A 向玩家 B 提供三个苹果）
  2. 若要在单个玩家的清单集合之间转移项目（例如，玩家 A 将其长剑从巫师角色的清单转移到武士角色的清单）
  3. 若要在单个玩家的清单中转移项目以创建、删除和操作项目堆栈（例如，玩家 A 将其 10 枚金币的堆栈拆分为三枚和七枚金币的两个堆栈）

Amount 和 GivingItem 参数用于表示转移的项目和数量。 ReceivingItem 表示接收玩家帐户的项目目的地。 GivingItem 和 ReceivingItem 两个参数都是 InventoryItemReference 对象，包含项目的 Id 和 StackId。 GivingItem 和 ReceivingItem 两者都可以为空，以处理一个实体不会转移项目的转移。 除非指定，否则在添加/转移到玩家的清单时，所有项目的 StackId 都设为 default。

1. 玩家之间的转移

对于玩家之间的转移，应指定 GivingEntity 和 ReceivingEntity，分别表示转移项目的玩家和接收项目的玩家。

玩家之间的 TransferInventoryItems 请求示例：

{
    "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. 集合之间的转移

对于集合之间的转移，应设置 GivingCollectionId 和 ReceivingCollectionId，分别表示请求转移的来源和目标的清单集合 ID。

集合之间的 TransferInventoryItems 请求示例：

{
    "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
}

上述请求将 10 个项目从玩家的 default 集合转移到 main_character 集合。

有关集合的详细信息，请参阅此处。

3. 堆栈之间的转移

对于堆栈之间的转移，应指定请求的 GivingItem 和 ReceivingItem 的 StackId。

堆栈之间的 TransferInventoryItems 请求示例：

{
    "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
}

上述请求将 10 个项目从玩家的 default 堆栈转移到 MyNewStack 堆栈。

有关堆栈的详细信息，请参阅此处。

ExecuteInventoryOperations API

可以使用 ExecuteInventoryOperations API 在单个请求中批处理多个清单操作。 操作将按指定的请求顺序进行，如果无法执行操作，将取消整个操作集。

ExecuteInventoryOperations 采用一个操作列表的参数 Operation。 Operation 列表中最多可以有 10 个操作，但操作类型可以重复（例如，可以有 10 个添加操作）。 此外，在单个请求中可以修改/添加的项目数量至多为 250 个。 例如，添加包含 50 个项目的捆绑包，将视为修改了 50 个项目。 有效的操作类型为：

  • 添加
  • 减
  • 更新
  • 购买
  • 转移*
  • 删除

注意

*批处理中仅支持单集合转移。

请求 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
            }
        }
    ]
}

幂等性

调用清单 API 时，可以传入一个 IdempotencyId，在出于回退或冗余目进行重复调用的情况下使用。 如果多个 API 调用相同的 IdempotencyId，系统将确保只处理其中一个请求。

例如，可以多次调用以下 PurchaseItem API 请求，但由于所有请求都使用相同的 IdempotencyId，因此只会为该玩家清单进行一次购买。

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

IdempotencyId 将存储并强制执行 14 天，之后可以再次使用该 ID。

注意

对不同的请求类型使用相同的 IdempotencyId 方法将导致冲突并报错。

显示属性

显示属性是可添加到玩家清单中的项目和项目堆栈的自定义项目属性。

可通过 AddInventoryItems、PurchaseInventoryItems、TransferInventoryItems和 UpdateInventoryItems 操作添加这些属性。

将属性添加到新堆栈/项目

对于 AddInventoryItems、PurchaseInventoryItems 和 TransferInventoryItems API，只能在创建新堆栈时添加显示属性。 若要为新项目设置显示属性，必须在 API 请求中设置 NewStackValues 参数。

包含 NewStackValues 的 AddInventoryItems 请求示例：

{
    "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"
        }
    }
}

有关堆栈的详细信息，请参阅此处。

将属性更新到现有堆栈/项目

若要更新现有项目的显示属性，可以使用 UpdateInventoryItems API 直接修改属性。

包含 DisplayProperties 的 UpdateInventoryItems 请求示例：

{
    "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"
        }
    }
}