インベントリ

[アーティクル]
07/13/2023

Important

エコノミー v2 が一般提供になりました。サポートとフィードバックについては、PlayFab フォーラムをご利用ください。

PlayFab インベントリ API は、プレイヤーインベントリおよびインベントリデータの管理と保存を可能にする API です。スタックやコレクションなどの機能により、プレイヤーインベントリの構造を柔軟に管理でき、あらゆるゲームで使用できるシステムを実現可能です

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

以下の API は、プレイヤーのインベントリ内のアイテムを追加、削除、更新、削除する操作に使用されます。アイテム数の制限は現在 3,500 個であり、この上限を超えるとエラーが発生します。

ゲームマネージャーで、Players を開きます
New Player の確認または作成操作の対象プレイヤーを選択し、Inventory (V2) に移動します

プレイヤーのインベントリを取得するには、GetInventoryItems を使用できます。プレイヤーの権限は、自分自身のインベントリのみに対するアクセスと操作のみに制限されています。タイトルエンティティでは、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
        }
    ],
}

インベントリアイテムの移動

TransferInventoryItems API には、3 つの異なる使用方法があります。

プレイヤー間でアイテムを譲渡する (たとえば、プレイヤー A がプレイヤー B にリンゴを 3 個渡す)
1 人のプレイヤーが自分のインベントリコレクション間でアイテムを移動する (たとえば、プレイヤー A がウィザードキャラクターのインベントリから戦士キャラクターのインベントリへと長剣を動かす)
1 人のプレイヤーのインベントリにあるアイテムを移動することで、アイテムスタックを作成、削除、操作する (たとえば、プレイヤー A が金貨 10 枚のスタックを分け、金貨 3 枚のスタックと金貨 7 枚ののスタックにする)

パラメーター 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
}

上の例は、プレイヤーのコレクション default からコレクション main_character へとアイテム 10 個を移動する要求です。

コレクションの詳細については、こちらを参照してください。

3. スタック間での移動

スタック間でアイテムを移動する場合は、GivingItem の StackId と、要求の ReceivingItem を指定する必要があります。

スタック間での 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 リストに含められる操作は最大 10 個ですが、同じ種類の操作を繰り返すこともできます (たとえば、10 個の Add 操作を実行する要求は有効です)。また、1 回の要求で変更または追加できるアイテムの数は 250 個までに制限されています。たとえば、50 個のアイテムを含んだバンドルを追加する操作は、50 個のアイテムに対する変更とカウントされます。有効な操作の種類は以下のとおりです。

[追加]
減算
アップデート
購入
Transfer*
削除

注意

* 1 つのバッチ内では、1 つのコレクションの移動のみがサポートされます。

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 を 1 つ渡すことができます。これは、フォールバック目的または冗長性目的のために繰り返し呼び出しを実行する状況で使用されます。複数の 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 日間にわたって保持され、適用されます。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"
        }
    }
}

インベントリ

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