インベントリ

Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、PlayFab フォーラムを参照してください。

PlayFab Inventory API を使用すると、プレイヤーのインベントリとインベントリデータを管理および保存できます。スタックやコレクションなどの機能によって、プレイヤーのインベントリを柔軟に構造化でき、あらゆるゲームで動作します。

プレイヤーインベントリの管理

以下の API を使用して、プレイヤーのインベントリ内のアイテムを追加、削除、更新、削除できます。現在の上限は 10000 アイテムで、それを超えるとエラーが発生します。

プレイヤーのインベントリの取得

Game Manager

Game Manager で Players に移動します。
表示したいプレイヤーを選択するか、New Player を作成し、Inventory (V2) に移動します。

API

GetInventoryItems を使用してプレイヤーのインベントリを取得できます。プレイヤーは自分自身のインベントリにのみアクセスして操作できます。Title Entity では 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 は、アイテム 1 つあたりの価格を示すアイテムと数量のリストです。これらの価格は、カタログまたは指定されたストアで構成された値と一致する必要があります。
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) を通じた実際の通貨での購入には、対応する Redeem API (RedeemAppleAppStoreInventoryItems、RedeemGooglePlayInventoryItems、RedeemSteamInventoryItems、RedeemMicrosoftStoreInventoryItems など) を使用してください。これらの API は、購入レシートをマーケットプレイスで検証し、アイテムをプレイヤーのインベントリに付与します。詳細については、Marketplace Redemption を参照してください。

バンドル

バンドルが購入されると (PurchaseInventoryItems またはマーケットプレイスの Redeem API を介して)、バンドルはプレイヤーのインベントリに 自動的にアンパック されます。バンドルの ItemReferences で参照されている個々のアイテムが直接付与されます。バンドル自体はプレイヤーのインベントリのアイテムとしては表示されません。たとえば、2 個の Laser Sword と 2 個の Laser Gun を含むバンドルを購入すると、それらのアイテムが個別に付与されます。バンドルの PriceOptions で定義された仮想通貨のコストは、トランザクションの一部としてプレイヤーのインベントリから差し引かれます。 AlternateIds を介してマーケットプレイス商品にリンクされているバンドルは、引き換え時に同じアンパック動作に従います。バンドルの作成に関する詳細は、バンドルを参照してください。

インベントリアイテムの転送

TransferInventoryItems API は 3 種類の方法で使用できます。

プレイヤー間でアイテムを転送する (たとえば、プレイヤー A がプレイヤー B に 3 個のリンゴを渡す)
単一プレイヤーのインベントリコレクション間でアイテムを転送する (たとえば、プレイヤー A が Wizard キャラクターのインベントリから Warrior キャラクターのインベントリに Long sword を移動する)
単一プレイヤーのインベントリ内でアイテムスタックを作成、削除、操作するために転送する (たとえば、プレイヤー A が 10 個の Gold Coin のスタックを 3 個と 7 個の 2 つのスタックに分割する)

GivingItem および Amount パラメーターは、転送されるアイテムと数量を表します。ReceivingItem は、受信側プレイヤーのアカウントにおけるアイテムの宛先を表します。GivingItem および ReceivingItem パラメーターはいずれも、アイテムの Id と StackId を含む InventoryItemReference オブジェクトです。エンティティの一方がアイテムを転送しない場合の転送を処理するため、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 と、転送先のインベントリコレクション 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
}

上記のリクエストは、プレイヤーの default コレクションから main_character コレクションに、そのアイテム 10 個を転送します。コレクションに関する詳細は、こちらを参照してください。

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
}

上記のリクエストは、プレイヤーの default スタックから MyNewStack スタックに、そのアイテム 10 個を転送します。スタックに関する詳細は、こちらを参照してください。

ExecuteInventoryOperations API

ExecuteInventoryOperations API を使用すると、複数のインベントリ操作を 1 つのリクエストにバッチ処理できます。操作は指定されたリクエスト順に実行され、実行できない操作があると、操作セット全体がキャンセルされます。 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
            }
        }
    ]
}

べき等性

Inventory API を呼び出す際、フォールバックまたは冗長性のために繰り返し呼び出しが行われる状況で使用できる IdempotencyId を渡すことができます。複数の API 呼び出しが同じ IdempotencyId を持つ場合、システムはそれらのリクエストのうち 1 つだけを処理することを保証します。たとえば、次の PurchaseItem API リクエストは複数回呼び出せますが、すべてのリクエストが同じ IdempotencyId を持っているため、そのプレイヤーのインベントリでは 1 回だけ購入が実行されます。

{
    "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 を参照してください。

表示プロパティ

表示プロパティは、プレイヤーのインベントリ内のアイテムやアイテムスタックに追加できるカスタムアイテムプロパティです。これらのプロパティは、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 と同時実行制御

表示プロパティ

新しいスタック/アイテムへのプロパティの追加

既存のスタック/アイテムのプロパティの更新