堆栈

项目
07/13/2023

重要

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

经济 V2 清单服务引入了堆栈的概念，可为清单需求增加更大的灵活性和支持。堆栈允许同一项的单独和不同的实例存在于同一清单中。此功能允许使用游戏内组织方案、设置不同的项目属性等功能！

相同 Id 的项目可以存储为该项目的堆栈，每个项目都有自己的数量，并按 StackId 进行区分。如果未指定，清单操作通常会使用具有以下 StackId 的默认堆栈： default 可以删除默认堆栈。下次在没有 StackId (或使用默认 StackId) 的情况下进行添加/传输时，将重新创建默认堆栈

管理清单和堆栈

下面是清单 API 及其与堆栈的交互的详细介绍。

添加清单项

在 AddInventoryItems API 中，可以在 Item 参数中定义 StackId。此参数定义要增加的堆栈或要创建的新堆栈的 ID。

包含 StackId 的示例 AddInventoryItems 请求：

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

上述请求将创建一个数量为 5 且 StackId 为 NewStack 的项目的全新堆栈，或者将 5 添加到现有 NewStack 堆栈 (如果已存在)

减去清单项

在 SubtractInventoryItems API 中，StackId 用于定义要从中减去的堆栈。此外，还可以设置一个 DeleteEmptyStacks 布尔值，如果减去的数量导致堆栈的数量为 0，则删除该堆栈。

尝试从堆栈中减去大于当前堆栈数量的数量将引发错误。

带有 StackId 的示例 SubtractInventoryItems 请求：

{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "NewStack"
    },
    "Amount": 5,
    "DeleteEmptyStacks": true,
}

上述请求将从 ID 为 NewStack 的堆栈中减去 5，如果堆栈的确切数量为 5，则会删除该堆栈。

更新清单项

在 UpdateInventoryItems API 中，可以在 Item 参数中定义 StackId。此参数定义正在更新的堆栈或正在创建的新堆栈的 ID。

请求 UpdateInventoryItems 示例：

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

上述请求将创建一个数量为 5 且 StackId 为 NewStack 的项目的全新堆栈，或者将 NewStack 的数量设置为 5 (如果已存在)

删除清单项

DeleteInventoryItems API 用于从玩家的清单中删除整个项目堆栈。可以提供 StackId 来定义要删除的项目的特定堆栈。

请求 DeleteInventoryItems 示例：

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

购买清单项

PurchaseInventoryItems API 使用商品的目录定义价格，并从玩家的清单中扣除成本，并将其与所需数量的项目进行交换。必须指定要购买的 Item 以及要购买的项目的 Amount。

使用堆栈进行购买时，有几个相关的参数：

对于 PriceAmounts 可以为每个价格项目定义一个可选 StackId (即，所花费的项目)，以定义将从中扣除的已花费项目的堆栈
对于 Item 对象，可以定义一个可选的 StackId，表示将用于放置接收项目的堆栈
可以设置一个 DeleteEmptyStacks 布尔值，如果减去的数量导致堆栈的数量为 0，则删除该堆栈。

TODO 添加链接

包含堆栈的示例 PurchaseInventoryItems 请求：

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

转移清单项

将 TransferInventoryItems API 与堆栈一起使用时，有一些相关参数：

在 GivingItem 对象中，可以定义一个可选的 StackId，表示将从中获取给定项目的堆栈
在 ReceivingItem 对象中，可以定义一个可选的 StackId，表示将用于放置接收项目的堆栈
可以设置一个 DeleteEmptyStacks 布尔值，如果 GivingItem 数量导致堆栈的数量为 0，则删除该堆栈

包含堆栈的示例 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,
    "DeleteEmptyStacks": true
}

ExecuteInventoryOperations API

可以在 ExecuteInventoryOperations API 中的 Operation 对象中使用 StackId 和 DeleteEmptyStacks 参数。这些参数允许使用堆栈对多个清单进行批处理操作。

包含堆栈的示例 ExecuteInventoryOperations 请求：

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

使用 DisplayProperties 和 NewStackValues 添加自定义属性

可以使用 DisplayProperties 参数将自定义项属性设置为清单项。可以在 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 直接修改属性。

通过

堆栈