庫存

Economy v2 現已正式推出。如需支援與意見反應，請前往 PlayFab 論壇。

PlayFab 庫存 API 可讓您管理與儲存玩家庫存及庫存資料。堆疊 (Stacks) 與集合 (Collections) 等功能讓您能彈性地建構玩家庫存，使這個系統適用於任何遊戲

管理玩家庫存

下列 API 可協助新增、移除、更新及刪除玩家庫存中的物品。目前的上限為 10000 個物品，超過此上限時會收到錯誤。

取得玩家的庫存

Game Manager

在 Game Manager 中，瀏覽至 Players
選取您要檢視的玩家或建立 New Player，然後前往 Inventory (V2)

API

您可以使用 GetInventoryItems 取得玩家的庫存。玩家僅能存取及操作自己的庫存。遊戲實體 (Title Entities) 可以傳入 Entity 參數，以指出要存取哪位玩家的庫存。 GetInventoryItems 要求範例：

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

如需使用 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 是選用參數，代表要從哪個商店購買物品。如需商店的詳細資訊，請參閱這裡

PurchaseInventoryItems 要求範例：

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

PurchaseInventoryItems API 用於以虛擬貨幣進行的購買。若要透過外部市集 (Apple App Store、Google Play、Steam、Microsoft Store) 進行真實貨幣購買，請使用對應的兌換 API (例如 RedeemAppleAppStoreInventoryItems、RedeemGooglePlayInventoryItems、RedeemSteamInventoryItems 或 RedeemMicrosoftStoreInventoryItems)。這些 API 會向市集驗證購買收據，並將物品授與至玩家的庫存。如需詳細資訊，請參閱市集兌換。

組合包

購買組合包時 (透過 PurchaseInventoryItems 或市集兌換 API)，組合包會自動拆開至玩家的庫存中。組合包 ItemReferences 中參考的個別物品會直接授與，組合包本身不會以物品的形式出現在玩家的庫存中。例如，購買包含 2 把雷射劍和 2 把雷射槍的組合包時，會個別授與這些物品。組合包 PriceOptions 中定義的虛擬貨幣費用，會在交易中從玩家的庫存中扣除。透過 AlternateIds 連結至市集產品的組合包，在兌換時也會遵循相同的拆開行為。如需建立組合包的詳細資訊，請參閱組合包。

轉移庫存物品

TransferInventoryItems API 可透過三種不同方式使用。

在玩家之間轉移物品 (例如，玩家 A 將三顆蘋果給玩家 B)
在單一玩家的庫存集合之間轉移物品 (例如，玩家 A 將長劍從巫師角色的庫存移至戰士角色的庫存)
在單一玩家的庫存內轉移物品，以建立、移除及操作物品堆疊 (例如，玩家 A 將 10 枚金幣的堆疊分成三枚和七枚金幣的兩個堆疊)

GivingItem 和 Amount 參數用於表示轉移的數量與物品。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 清單中最多可以有 50 個作業，但作業類型可以重複 (例如，10 個 Add 作業是有效的)。單一要求中可修改/新增的物品也有 300 個的上限。例如，新增包含 50 個物品的組合包會計為修改 50 個物品。有效的作業類型如下：

Add
Subtract
Update
Purchase
Transfer*
Delete

*批次中僅支援單一集合轉移。

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 會造成衝突並擲回錯誤。

ETag 與並行控制

庫存寫入 API 透過 ETag 和 HTTP 標頭支援開放式並行控制。如需完整詳細資訊，請參閱庫存 ETag。

顯示屬性

顯示屬性 (Display Properties) 是可新增至玩家庫存中物品與物品堆疊的自訂物品屬性。這些屬性可以透過 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"
        }
    }
}

​庫存

​管理玩家庫存

​取得玩家的庫存

​Game Manager

​API

接續權杖

​新增庫存物品

​減少庫存物品

​更新庫存物品

​刪除庫存物品

​購買庫存物品

​組合包

​轉移庫存物品

​1. 在玩家之間轉移

​2. 在集合之間轉移

​3. 在堆疊之間轉移

​ExecuteInventoryOperations API

​等冪性

​ETag 與並行控制

​顯示屬性

​將屬性新增至新的堆疊/物品

​更新現有堆疊/物品的屬性

庫存

管理玩家庫存

取得玩家的庫存

Game Manager

API

新增庫存物品

減少庫存物品

更新庫存物品

刪除庫存物品

購買庫存物品

組合包

轉移庫存物品

1. 在玩家之間轉移

2. 在集合之間轉移

3. 在堆疊之間轉移

ExecuteInventoryOperations API

等冪性

ETag 與並行控制

顯示屬性

將屬性新增至新的堆疊/物品

更新現有堆疊/物品的屬性