> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # PlayFab Inventory API > プレイヤー インベントリの管理、アイテムの付与、通貨残高の追跡、スタックの読み取りを行うための PlayFab Economy v2 Inventory API の概要。 # インベントリ Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、[PlayFab フォーラム](https://community.playfab.com) を参照してください。 PlayFab Inventory API を使用すると、プレイヤーのインベントリとインベントリ データを管理および保存できます。スタックやコレクションなどの機能によって、プレイヤーのインベントリを柔軟に構造化でき、あらゆるゲームで動作します。 ## プレイヤー インベントリの管理 以下の API を使用して、プレイヤーのインベントリ内のアイテムを追加、削除、更新、削除できます。現在の上限は 10000 アイテムで、それを超えるとエラーが発生します。 ### プレイヤーのインベントリの取得 #### Game Manager 1. [Game Manager](/services/playfab/live-service-management/gamemanager) で `Players` に移動します。 2. 表示したいプレイヤーを選択するか、`New Player` を作成し、`Inventory (V2)` に移動します。 #### API `GetInventoryItems` を使用してプレイヤーのインベントリを取得できます。プレイヤーは自分自身のインベントリにのみアクセスして操作できます。Title Entity では `Entity` パラメーターを渡して、アクセスしたいプレイヤーのインベントリを指定できます。 `GetInventoryItems` リクエストの例: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "CollectionId": "main_character", "Count": 15, "ContinuationToken": "abc=" } ``` *** `CollectionId` の使用と、プレイヤーごとに複数のインベントリを持つ方法の詳細については、[こちら](/services/playfab/economy-monetization/economy-v2/inventory/collections) を参照してください。 ##### 継続トークン インベントリの検索レスポンスから返される `ContinuationToken` フィールドは、複数の結果を分割してページングするためにインベントリ リクエストに渡すことができます。 ### インベントリ アイテムの追加 `AddInventoryItems` API は、特定のプレイヤーのインベントリにアイテムを直接追加します。`EntityId`、`ItemId`、`Amount` パラメーターを受け取り、指定されたアイテムをプレイヤーのインベントリに追加します。 `AddInventoryItems` リクエストの例: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 10, } ``` ### インベントリ アイテムの減算 `SubtractInventoryItems` API は、プレイヤーのインベントリ内のアイテムを特定の量だけ直接減らします。`EntityId`、`ItemId`、`Amount` パラメーターを受け取り、指定された量のアイテムを削除します。現在利用可能な量を超える量を削除しようとすると、この API はエラーをスローします。 `SubtractInventoryItems` リクエストの例: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 10, } ``` ### インベントリ アイテムの更新 `UpdateInventoryItems` API は、プレイヤーのインベントリ内のアイテムを特定の量に直接設定します。`EntityId`、`ItemId`、`Amount` パラメーターを受け取り、指定された量のアイテムに設定します。この API はアイテムの量を増減させるだけでなく、アイテムが存在しない場合はプレイヤーのインベントリに追加することもできます。 `UpdateInventoryItems` リクエストの例: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "Amount": 10 } } ``` ### インベントリ アイテムの削除 `DeleteInventoryItems` API は、プレイヤーのインベントリからアイテムのスタック全体を削除します。 `DeleteInventoryItems` リクエストの例: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, } ``` ### インベントリ アイテムの購入 `PurchaseInventoryItems` API は、カタログで定義されたアイテムの価格を使用し、プレイヤーのインベントリからコストを差し引いて、希望する数量のアイテムと交換します。購入したい `Item` と、購入したい `Amount` を指定する必要があります。 `PurchaseInventoryItems` API に固有の主要なパラメーターがいくつかあります。 * `PriceAmounts` は、アイテム 1 つあたりの価格を示すアイテムと数量のリストです。これらの価格は、カタログまたは指定されたストアで構成された値と一致する必要があります。 * `StoreId` は、アイテムが購入されるストアのオプション パラメーターです。ストアの詳細については、[こちら](/services/playfab/economy-monetization/economy-v2/catalog/stores) を参照してください。 `PurchaseInventoryItems` リクエストの例: ```json theme={null} { "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) を通じた実際の通貨での購入には、対応する Redeem API (`RedeemAppleAppStoreInventoryItems`、`RedeemGooglePlayInventoryItems`、`RedeemSteamInventoryItems`、`RedeemMicrosoftStoreInventoryItems` など) を使用してください。これらの API は、購入レシートをマーケットプレイスで検証し、アイテムをプレイヤーのインベントリに付与します。詳細については、[Marketplace Redemption](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview) を参照してください。 #### バンドル バンドルが購入されると (`PurchaseInventoryItems` またはマーケットプレイスの Redeem API を介して)、バンドルはプレイヤーのインベントリに **自動的にアンパック** されます。バンドルの `ItemReferences` で参照されている個々のアイテムが直接付与されます。バンドル自体はプレイヤーのインベントリのアイテムとしては表示されません。 たとえば、2 個の Laser Sword と 2 個の Laser Gun を含むバンドルを購入すると、それらのアイテムが個別に付与されます。バンドルの `PriceOptions` で定義された仮想通貨のコストは、トランザクションの一部としてプレイヤーのインベントリから差し引かれます。 `AlternateIds` を介してマーケットプレイス商品にリンクされているバンドルは、引き換え時に同じアンパック動作に従います。バンドルの作成に関する詳細は、[バンドル](/services/playfab/economy-monetization/economy-v2/catalog/bundles) を参照してください。 ### インベントリ アイテムの転送 `TransferInventoryItems` API は 3 種類の方法で使用できます。 1. プレイヤー間でアイテムを転送する (たとえば、プレイヤー A がプレイヤー B に 3 個のリンゴを渡す) 2. 単一プレイヤーのインベントリ コレクション間でアイテムを転送する (たとえば、プレイヤー A が Wizard キャラクターのインベントリから Warrior キャラクターのインベントリに Long sword を移動する) 3. 単一プレイヤーのインベントリ内でアイテム スタックを作成、削除、操作するために転送する (たとえば、プレイヤー A が 10 個の Gold Coin のスタックを 3 個と 7 個の 2 つのスタックに分割する) `GivingItem` および `Amount` パラメーターは、転送されるアイテムと数量を表します。`ReceivingItem` は、受信側プレイヤーのアカウントにおけるアイテムの宛先を表します。`GivingItem` および `ReceivingItem` パラメーターはいずれも、アイテムの `Id` と `StackId` を含む `InventoryItemReference` オブジェクトです。エンティティの一方がアイテムを転送しない場合の転送を処理するため、`GivingItem` および `ReceivingItem` はいずれも空にできます。特に指定しない限り、プレイヤーのインベントリに追加/転送されるとき、すべてのアイテムの `StackId` は `default` に設定されます。 #### 1. プレイヤー間の転送 プレイヤー間の転送の場合、`GivingEntity` および `ReceivingEntity` を指定します。これらは、それぞれアイテムを転送するプレイヤーと、アイテムを受け取るプレイヤーを表します。 プレイヤー間の `TransferInventoryItems` リクエストの例: ```json theme={null} { "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 と、転送先のインベントリ コレクション ID を表します。 コレクション間の `TransferInventoryItems` リクエストの例: ```json theme={null} { "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 } ``` 上記のリクエストは、プレイヤーの `default` コレクションから `main_character` コレクションに、そのアイテム 10 個を転送します。 コレクションに関する詳細は、[こちら](/services/playfab/economy-monetization/economy-v2/inventory/collections) を参照してください。 #### 3. スタック間の転送 スタック間の転送の場合、リクエストの `GivingItem` と `ReceivingItem` の `StackId` を指定します。 スタック間の `TransferInventoryItems` リクエストの例: ```json theme={null} { "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 } ``` 上記のリクエストは、プレイヤーの `default` スタックから `MyNewStack` スタックに、そのアイテム 10 個を転送します。 スタックに関する詳細は、[こちら](/services/playfab/economy-monetization/economy-v2/inventory/stacks) を参照してください。 ### ExecuteInventoryOperations API `ExecuteInventoryOperations` API を使用すると、複数のインベントリ操作を 1 つのリクエストにバッチ処理できます。操作は指定されたリクエスト順に実行され、実行できない操作があると、操作セット全体がキャンセルされます。 `ExecuteInventoryOperations` は、操作のリストである `Operation` パラメーターを受け取ります。`Operation` リスト内に含めることができる操作は最大 **50 操作** で、同じ操作タイプが繰り返されても構いません (たとえば、10 個の Add 操作は有効です)。また、単一のリクエストで変更/追加できるアイテム数は最大 **300 アイテム** に制限されています。たとえば、50 アイテムを含むバンドルを追加すると 50 アイテムの変更としてカウントされます。有効な操作タイプは次のとおりです。 * Add * Subtract * Update * Purchase * Transfer\* * Delete \*バッチ内では、単一コレクションの転送のみがサポートされます。 `ExecuteInventoryOperations` リクエストの例: ```json theme={null} { "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 } } ] } ``` ### べき等性 Inventory API を呼び出す際、フォールバックまたは冗長性のために繰り返し呼び出しが行われる状況で使用できる `IdempotencyId` を渡すことができます。複数の API 呼び出しが同じ `IdempotencyId` を持つ場合、システムはそれらのリクエストのうち 1 つだけを処理することを保証します。 たとえば、次の `PurchaseItem` API リクエストは複数回呼び出せますが、すべてのリクエストが同じ `IdempotencyId` を持っているため、そのプレイヤーのインベントリでは 1 回だけ購入が実行されます。 ```json theme={null} { "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 と同時実行制御 Inventory 書き込み API は、ETag および HTTP ヘッダーを通じた楽観的同時実行制御をサポートします。詳細については、[Inventory ETags](/services/playfab/economy-monetization/economy-v2/inventory/etags) を参照してください。 ### 表示プロパティ 表示プロパティは、プレイヤーのインベントリ内のアイテムやアイテム スタックに追加できるカスタム アイテム プロパティです。 これらのプロパティは、`AddInventoryItems`、`PurchaseInventoryItems`、`TransferInventoryItems`、および `UpdateInventoryItems` の操作によって追加できます。 #### 新しいスタック/アイテムへのプロパティの追加 `AddInventoryItems`、`PurchaseInventoryItems`、`TransferInventoryItems` API では、新しいスタックが作成されるときに **のみ** 表示プロパティを追加できます。新しいアイテムの表示プロパティを設定するには、API リクエストで `NewStackValues` パラメーターを設定する必要があります。 `NewStackValues` を含む `AddInventoryItems` リクエストの例: ```json theme={null} { "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" } } } ``` スタックに関する詳細は、[こちら](/services/playfab/economy-monetization/economy-v2/inventory/stacks) を参照してください。 #### 既存のスタック/アイテムのプロパティの更新 既存のアイテムの表示プロパティを更新するには、`UpdateInventoryItems` API を使用してプロパティを直接変更できます。 `DisplayProperties` を含む `UpdateInventoryItems` リクエストの例: ```json theme={null} { "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" } } } ``` ## Related topics - [PlayFab Inventory API](/ko/services/playfab/economy-monetization/economy-v2/inventory/index.md) - [PlayFab Inventory APIs](/services/playfab/economy-monetization/economy-v2/inventory/index.md) - [PFInventoryInventoryOperation](/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryoperation.md) - [PFInventoryInventoryItem](/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitem.md) - [Inventory Collections](/services/playfab/economy-monetization/economy-v2/inventory/collections.md)