> ## 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.

# Microsoft Store マーケットプレイスでの引き換え

> Microsoft Store のアドオンを作成し、PlayFab バンドルにリンクし、RedeemMicrosoftStoreInventoryItems で XBOX および Windows の購入を引き換えます。

# PlayFab と Microsoft Store をセットアップして購入を有効にする

このチュートリアルでは、次の方法を説明します。

* Microsoft Store で購入可能な製品を作成する
* それを PlayFab バンドルにマッピングする
* [RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API を使用して、購入したアイテムをプレイヤーのインベントリに引き換える

## 前提条件

1. PlayFab の [Game Manager](https://developer.playfab.com/) 内のタイトル。
2. [選択したタイトルと Microsoft Store 間の既存の統合](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft)。以下を含みます。
   * Game Manager にインストールおよび構成された **XBOX Network** アドオン。
   * Partner Center で構成された **Product Group**、**Dev Studio**、**Business Partner ID**。
3. アプリにアクセスできる [Partner Center](https://partner.microsoft.com/) アカウント。
4. Partner Center で既に作成されたアプリ。
5. Redeem API を呼び出すプレイヤーは、XBOX Live ID (たとえば `LoginWithXbox` 経由) を使用して PlayFab に認証されている必要があります。他の ID タイプ (CustomID や電子メールなど) で認証されたプレイヤーは、このフローに必要な XBOX コンテキストを持ちません。

## ステップ 1: Partner Center でアドオンを作成する

[マーケットプレイス統合のセットアップ](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft#step-1-create-your-add-on-in-partner-center) の一環として Partner Center でアドオンを作成していない場合は、以下の手順に従います。

1. [Partner Center](https://partner.microsoft.com/) にサインインし、アプリに移動します。
2. **Add-ons** の下で **Create a new add-on** を選択します。
3. 適切な製品タイプを選択します。
   * 再購入可能なアイテム (通貨、消耗品パック) には **Developer-managed consumable**。
   * 1 回限りの購入 (DLC、シーズン パス、コスメティック アンロック) には **Durable**。
4. アドオン構成 (価格、説明など) を完了し、送信します。
5. アドオンを作成したら、**Store ID** をメモします。Partner Center に表示される英数字文字列 (たとえば `9NBLGGH42CFD`) です。PlayFab のマーケットプレイス マッピングでは、開発者定義の Product ID やアドオン名 **ではなく** この値を使用します。

<Info>
  **Store 管理の消耗品はサポートされていません。** `RedeemMicrosoftStoreInventoryItems` API では、Developer-managed consumables と Durables のみが機能します。Partner Center は、Developer-managed consumables が XBOX でサポートされていないことを示唆する警告を表示することがあります。この警告は PlayFab の引き換えフローを使用する場合には適用されません。詳細については、[Choosing the right product type](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-choosing-the-right-product-type) を参照してください。
</Info>

6. テストしたいサンドボックスまたは環境にアドオンを公開します。

## ステップ 2: Game Manager でバンドルを作成する

<Note>
  **Game Manager** でバンドルを作成する前に、バンドルに追加したいアイテムをカタログで作成および公開してください。アイテムの作成方法についてのガイダンスが必要な場合は、[このステップ](/services/playfab/economy-monetization/economy-v2/tutorials/craftingGame/crafting-game-game-manager#step-4---create-your-first-item) を参照してください。
</Note>

**Game Manager** と **Microsoft Store** の間のマーケットプレイス マッピングを有効にするには、Game Manager で **バンドル** を作成する必要があります。バンドルには数量の異なる複数のアイテムを含めることができ、引き換えられると PlayFab がそれらをプレイヤーのインベントリに追加します。次の手順に従います。

1. [Game Manager](https://developer.playfab.com/) に移動し、**タイトル** に移動します。
2. 左側のナビゲーション メニューから **Engage** > **Economy** を選択します。
3. **Bundles** タブを選択します。
4. **New bundle** を選択します。
5. アイテムや価格など、**バンドル** に追加したい情報を追加します。
6. ページの末尾までスクロールし、プレイヤーがすぐに引き換えられるようにしたい場合は **Save and publish** を選択します。後日公開する場合は **Save as draft** を選択します。

### バンドルにアイテムを追加する

バンドル自体はプレイヤーにアイテムを付与しません。まずアイテムをバンドルにリンクする必要があります。引き換えられると、バンドルは特定のプレイヤーにそれらのアイテムを付与します。

バンドルにアイテムを追加するには:

1. 編集モードで **Items** セクションに移動します。
2. **Add** を選択します。すべてのカタログ アイテムを表示するウィンドウが表示されます。
3. 目的のアイテムを見つけ、その横の **Add** を選択します。
4. 下部の **Add** ボタンを選択します。

## ステップ 3: マーケットプレイス マッピングを有効にする

プレイヤーが Microsoft Store から製品を購入したときに Game Manager で正しく一致して割り当てられるようにするには、バンドルの **Marketplace Mapping** を構成する必要があります。

1. 編集モードでバンドルに移動します。
2. **Marketplace Mapping** セクションまでスクロールします。
3. **Marketplace** ドロップダウンから **MicrosoftStore** を選択します (大文字と小文字が区別されます。正確に `MicrosoftStore` である必要があります)。
4. **Marketplace ID** には、Partner Center の正確な **Store ID** (たとえば `9NBLGGH42CFD`) を使用します。開発者定義の Product ID は **使用しないでください**。
5. その行の右側にある **+** を選択し、変更を **Save** します。

<Info>
  引き換え時に一致するように、バンドルは **公開されている** 必要があります (下書きのままにしないでください)。引き換え API は未公開のカタログ アイテムを検出しません。
</Info>

代替 ID の詳細については、[Alternate IDs](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids) を参照してください。

## ステップ 4: プレイヤーを認証する

引き換え呼び出しを行う前に、プレイヤーが適切に認証されていることを確認する必要があります。XBOX および Microsoft Store のシナリオでは、[LoginWithXbox](https://learn.microsoft.com/en-us/rest/api/playfab/client/authentication/login-with-xbox) を使用してプレイヤーを PlayFab に認証します。

`LoginWithXbox` の呼び出しが成功すると、PlayFab は `EntityToken` を返します。これを引き換え呼び出しのヘッダーで `X-EntityToken` キーとして使用する必要があります。

## ステップ 5: XBOX トークンを取得する

`RedeemMicrosoftStoreInventoryItems` API では、`XboxToken` パラメーターに有効な XBOX トークンが必要です。このトークンは、認証に使用される `EntityToken` とは別のものです。

* **GDK C API** を使用している場合は、次を使用します。

  ```cpp theme={null}
  XUserGetTokenAndSignatureAsync  // メソッド "POST"、URL "https://playfabapi.com/"、空のボディ "" を使用
  ```

3 つのパラメーター (method、URL、body) はすべて、表示されたとおりに正確に指定する必要があります。トークンを誤って取得すると、Microsoft Store Collections API のクエリはサイレントに失敗し、アイテムを返しません。

## ステップ 6: 購入する

プレイヤーは PlayFab を通じて引き換える前に、Microsoft Store からアドオンを購入する必要があります。この購入は XBOX または Windows Store のインターフェイスから行うことができます。

<Note>
  サンドボックス環境でテストしている場合は、プレイヤー アカウントとアドオンの両方が同じサンドボックスに公開されていることを確認してください。引き換え API が引き換え対象のアイテムを見つけられるように、プレイヤーのアカウントには **未引き換えの購入** が必要です。
</Note>

## ステップ 7: 購入を引き換える

プレイヤーが認証され、XBOX トークンが取得され、購入が完了したら、[RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API を呼び出す準備ができています。

`EntityToken` を `X-EntityToken` ヘッダーとして含め、リクエスト ボディで XBOX トークンを指定します。

```json theme={null}
{
    "XboxToken": "{Your Xbox token from GetTokenAndSignatureAsync}"
}
```

### 引き換えの仕組み

`RedeemMicrosoftStoreInventoryItems` 呼び出しが行われると、PlayFab は XBOX トークンを使用して Microsoft Store Collections API に、プレイヤーのアカウントに関連付けられた未引き換えの購入がないかクエリします。次に、それらの購入を PlayFab バンドルのマーケットプレイス マッピングで構成された **Store ID** と照合し、対応するアイテムを付与します。

成功のレスポンスには、`200` ステータス コードと共に、[RedeemMicrosoftStoreInventoryItemsResponse](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) が含まれ、以下が含まれます。

* **Succeeded** — 正常に引き換えられたアイテムのリスト。
* **Failed** — 引き換えに失敗したアイテムのリスト。
* **TransactionIds** — 各引き換え取引の ID。

各引き換えアクションは、プレイヤーの取引履歴に対応するイベントをトリガーし、これは [Game Manager](https://developer.playfab.com/) のプレイヤー概要ページの **Transaction History (V2)** タブから取得できます。

プレイヤーの取引履歴のレコードと共に、`items_redeemed` **PlayStream** イベントもトリガーされて記録されます。タイトルのこれらのログには、[Game Manager](https://developer.playfab.com/) の左側のナビゲーション バーの **Analyze** セクションの下にある **Data** ページに移動することでアクセスできます。

### 開発者管理の消耗品のフルフィルメント

引き換えられた製品が **Developer-managed consumable** の場合、PlayFab は引き換えが成功した後、自動的にそれを **fulfilled** (消費済み) として Microsoft Store に報告します。プレイヤーが同じ消耗品を再購入できるようにするには、フルフィルメント ステップが必要です。引き換えが成功した後に消耗品がフルフィルメント済みとして表示されない場合は、`RedeemMicrosoftStoreInventoryItems` の呼び出しを再試行してください。問題が続く場合は、サポート チャネルを通じて PlayFab チームにエスカレーションしてください。Durable は 1 回限りの購入であるため、フルフィルメントは必要ありません。詳細については、[Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds) を参照してください。

## トラブルシューティング

引き換え呼び出しが `200` を返すのに、3 つの配列 (`Succeeded`、`Failed`、`TransactionIds`) がすべて空である場合、Microsoft Store Collections API が一致するアイテムを見つけていません。この結果は通常、構成の問題を示しています。一般的な原因と解決策の完全なリストについては、Microsoft Store 統合ガイドの [トラブルシューティング セクション](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft#troubleshooting) を参照してください。

API が HTTP エラー (400 など) を返す場合は、`InvalidCatalogItemConfiguration`、`InvalidXboxLiveToken`、`AccountNotLinked` などのコードのエラー レスポンスを確認してください。

## 関連項目

* [Microsoft Store マーケットプレイス統合](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft)
* [RedeemMicrosoftStoreInventoryItems API リファレンス](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items)
* [不正防止のクイックスタート](/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart)
* [XBOX Live アドオンの構成](/services/playfab/identity/player-identity/platform-specific-authentication/xbox-live-add-on)
* [Apple アプリを Game Manager に正常に統合する方法](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/apple)
* [Google アプリを Game Manager に正常に統合する方法](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/google)


## Related topics

- [Steam マーケットプレイスでの引き換え](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/steam.md)
- [Google マーケットプレイスでの引き換え](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/google.md)
- [マーケットプレイスの引き換え - 概要](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview.md)
- [マーケットプレイス統合 - Microsoft Store](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft.md)
- [マーケットプレイスのエラー処理](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-error-handling.md)