> ## 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
> XBOX および Windows のアプリ内購入引き換え用に、Partner Center アドオンを設定し、Microsoft Store 製品を PlayFab Economy v2 バンドルにリンクします。
# マーケットプレイス統合: Microsoft Store
このチュートリアルでは、[RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API を使用して、PlayFab Economy v2 経由で Microsoft Store のアプリ内購入 (XBOX を含む) を引き換える方法を説明します。
このチュートリアルの終了時点で、次のことができるようになります。
* Partner Center でアドオンを作成する
* 必要な Partner Center と PlayFab の設定を構成する
* Microsoft Store 製品を PlayFab カタログのバンドルにリンクする
* Redeem API を呼び出し、プレイヤーのインベントリでアイテムを確認する
## 前提条件
1. アプリにアクセスできる [Partner Center](https://partner.microsoft.com/) アカウント。
2. Partner Center で既に作成されたアプリ。
3. [Game Manager](https://developer.playfab.com/) で既に作成されたタイトル。
4. Redeem API を呼び出すプレイヤーは、XBOX Live ID (たとえば `LoginWithXbox` 経由) を使用して PlayFab に認証されている必要があります。他の ID タイプ (CustomID や電子メールなど) で認証されたプレイヤーは、このフローに必要な XBOX コンテキストを持ちません。
## サポートされる製品タイプ
`RedeemMicrosoftStoreInventoryItems` API は、次の Microsoft Store 製品タイプをサポートしています。
* **開発者管理の消耗品** — 購入、使用、再購入が可能な製品 (たとえばゲーム内通貨パック)。フルフィルメントの追跡はゲーム サービスの責任です。
* **耐久財** — 1 回購入すると永続的に所有される製品 (たとえば DLC、拡張パック、シーズン パス、コスメティック アイテム)。
**Store 管理の消耗品はサポートされていません。** PlayFab Economy v2 は Store 管理の消耗品を引き換えることができません。アドオンが Store 管理の消耗品として構成されている場合、Redeem API は空の結果を含む HTTP 200 レスポンスをエラーなしで返すため、問題の診断が困難になります。
## ステップ 1: 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. アドオン構成 (価格、説明など) を完了し、送信します。
Developer-managed consumable を作成すると、Partner Center は次の警告を表示します: *"XBOX requires consumables to be managed, so do not use this option and create a 'managed consumable' add-on instead. If you have any questions, contact your Microsoft representative."*\* この警告は XBOX プラットフォームの一般的なガイダンスを反映しており、**PlayFab の引き換えフローには適用されません**。Developer-managed consumable は、PlayFab の `RedeemMicrosoftStoreInventoryItems` API で使用すると XBOX で正しく機能します。安心してこの製品タイプで進めることができます。
5. アドオンを作成したら、**Store ID** をメモします。Partner Center に表示される英数字文字列 (たとえば `9NBLGGH42CFD`) です。PlayFab では、開発者定義の Product ID やアドオン名 **ではなく** この値を使用します。
製品タイプの詳細については、[Choosing the right product type](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-choosing-the-right-product-type) を参照してください。
## ステップ 2: Product Group、Dev Studio、Business Partner ID を構成する
このステップでは、プレイヤーの代わりに Microsoft Store Collections API を照会するために PlayFab が使用する、委任された XBOX Security Token Service (XSTS) トークン フローを構成します。
Product Group、Dev Studio、Business Partner ID の構成は、最もよく見落とされるステップです。これがないと、Redeem API 呼び出しは成功 (HTTP 200) しますが、Collections API はゼロ件のアイテムを返し、`Succeeded`、`Failed`、`TransactionIds` 配列が空でエラー メッセージなしという結果になります。
1. [Partner Center](https://partner.microsoft.com/) で **Developer Settings** > **XBOX Live** > **Web Services** に移動し、まだ生成していない場合は Business Partner Certificate を生成します。
2. **Developer Settings** > **XBOX Live** > **Business Partner** に移動し、relying party がひも付けられている Web サービスと一致する **Business Partner ID** をメモします。
3. **Dev Studio** を作成する (または既存のものを使用) し、その **Dev Studio ID** をステップ 2 の **Business Partner ID** と一致するように設定します。Dev Studio に既に異なる ID がある場合は、既存の値を変更するのではなく、新しい Dev Studio を作成してください。変更すると既存のサービスが壊れる可能性があります。
4. **Product Group** を作成し、ステップ 3 の Dev Studio に割り当てます。
5. ゲーム製品 **と** すべてのアドオンを **Included in this product group** リストに追加します。アイテムは "available" 側から "included" 側に明示的に移動する必要があります。
6. **Save** を選択します。
7. ゲームの **XBOX Settings** ページに移動し、リンクされた **Business Partner** がステップ 2 のものと一致することを確認します。
8. 対象のサンドボックスまたは RETAIL 環境で、ゲーム製品とすべてのアドオンを Microsoft Store に **再公開** します。
構成全体の詳細な手順については、[Configure products with delegated authentication (XSTS tokens)](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-authenticating-your-service#additional-configuration-required-to-view-and-manage-products-with-delegated-authentication-xsts-tokens) を参照してください。
## ステップ 3: Game Manager で XBOX Network アドオンを有効にする
XBOX Network アドオンは、Partner Center 製品を PlayFab タイトルにリンクし、Microsoft Store 引き換え用の XBOX トークン検証を有効にします。
1. [Game Manager](https://developer.playfab.com/) を開き、**タイトル** を選択します。
2. 左側のナビゲーション メニューから **Add-ons** を選択します。
3. **XBOX Network** アドオン (**Distribute for XBOX** と表示されます) を見つけて選択します。
4. ドロップダウンから正しい **Seller ID** を選択します。正しい Seller ID が表示されない場合は、**Sign in with a different partner center account** を選択します。
5. ドロップダウンから **Partner Center Product ID** を選択し、**XBOX Live Title ID** (10 進数) が Partner Center の **XBOX services** > **XBOX Settings** に表示されているものと一致することを確認します。
6. **Install XBOX Network** を選択して構成を保存します。
詳細については、[XBOX Live アドオンの構成](/services/playfab/identity/player-identity/platform-specific-authentication/xbox-live-add-on) を参照してください。
Game Manager には、別の **Microsoft Store** アドオン ページもあります (これも **Add-ons** の下)。構成は必要ありませんが、サポートされている製品タイプの確認や、Dev Studio ID と Business Partner ID のセットアップに関する詳細を含む有用なガイダンスが含まれています。
## ステップ 4: Marketplace Mapping を持つ PlayFab バンドルを作成する
Microsoft Store 製品を PlayFab カタログにリンクするには、**Marketplace Mapping** (AlternateId) を持つ **バンドル** を作成します。
1. [Game Manager](https://developer.playfab.com/) で、**Economy** > **Catalog (V2)** > **Bundles** に移動します。
2. **New bundle** を選択します (または既存のものを編集します)。
3. **Marketplace Mapping** セクションで、新しいマッピングを追加します。
* **Marketplace type** を `MicrosoftStore` に設定します (大文字と小文字が区別されます。正確に `MicrosoftStore` である必要があります)。
* **value** を Partner Center の正確な **Store ID** (たとえば `9NBLGGH42CFD`) に設定します。開発者定義の Product ID やアドオン名は使用しないでください。
4. このバンドルが引き換えられたときにプレイヤーが受け取るアイテム (たとえばゲーム内通貨、仮想アイテム) を追加します。
5. バンドルを **公開** します。未公開 (下書き) のバンドルは引き換え時に一致しません。
代替 ID の詳細については、[Alternate IDs](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids) を参照してください。
## ステップ 5: XBOX トークンを取得して提供する
[RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items) API を呼び出す際、`XboxToken` パラメーターに有効な XBOX トークンを提供する必要があります。
* **GDK C API** を使用している場合は、次を使用します。
```cpp theme={null}
XUserGetTokenAndSignatureAsync // メソッド "POST"、URL "https://playfabapi.com/"、空のボディ "" を使用
```
3 つのパラメーター (method、URL、body) はすべて、表示されたとおりに正確に指定する必要があります。トークンを誤って取得すると、Collections API のクエリはサイレントに失敗し、エラーなしで空の結果を返します。
## ステップ 6: 統合をテストする
統合を完了と見なす前に、エンド ツー エンドの完全なフローを検証してください。
1. アドオンが、テスト中のサンドボックスまたは環境に公開されていることを確認します。
2. XBOX Live ID を使用してテスト プレイヤーとしてサインインし、Microsoft Store 経由でアドオンのテスト購入を行います。Redeem API が検出するものが存在するようにするには、プレイヤーのアカウントに未引き換えの購入が必要です。
3. プレイヤーの `XboxToken` を使って `RedeemMicrosoftStoreInventoryItems` を呼び出します。
4. レスポンスの `Succeeded` 配列にエントリが含まれ、対応するアイテムがプレイヤーの PlayFab インベントリに表示されることを確認します。
**開発者管理の消耗品のフルフィルメント:** 開発者管理の消耗品が引き換えられた後、PlayFab は自動的にそれを Microsoft Store に **fulfilled** (消費済み) として報告します。プレイヤーが再度消耗品を購入できるようにするには、フルフィルメント ステップが必要です。引き換えが成功した後に消耗品がフルフィルメント済みとして表示されない場合は、`RedeemMicrosoftStoreInventoryItems` の呼び出しを再試行してください。問題が続く場合は、サポート チャネルを通じて PlayFab チームにエスカレーションしてください。詳細については、[Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds) を参照してください。
## トラブルシューティング
`RedeemMicrosoftStoreInventoryItems` 呼び出しが正常に返される (HTTP 200) ものの、レスポンスの `Succeeded`、`Failed`、`TransactionIds` 配列がすべて空である場合、Microsoft Store Collections API が引き換え対象の一致するアイテムを見つけていません。通常、この動作は構成の問題によって引き起こされます。以下の項目を確認してください。
| 問題 | 解決策 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **間違った製品タイプ** | アドオンが Store 管理の消耗品ではなく、**Developer-managed consumable** または **Durable** であることを確認してください。PlayFab は Store 管理の消耗品をサポートしていません。 |
| **PlayFab の Store ID が正しくない** | Marketplace Mapping の値が **Store ID** (`9NBLGGH42CFD` のような英数字文字列) と一致していることを確認してください。開発者定義の Product ID やアドオン名ではありません。 |
| **バンドルが公開されていない** | PlayFab カタログでバンドルを公開してください。下書きのバンドルは引き換え時に一致しません。 |
| **Product Group 構成が不足** | ゲームとアドオンが、正しい Dev Studio と Business Partner ID にひも付けられた Product Group に含まれていることを確認してください。Product Group の構成は最もよく見落とされるステップです。[ステップ 2](#step-2-configure-product-group-dev-studio-and-business-partner-id) を参照してください。 |
| **XBOX Network アドオンが構成されていない** | Game Manager で XBOX Network アドオンをインストールして構成してください。[ステップ 3](#step-3-enable-the-xbox-network-add-on-in-game-manager) を参照してください。 |
| **未引き換えの購入がない** | API が製品を検出して引き換えられるようにするには、プレイヤーに製品の未引き換え購入が必要です。まずテスト購入を行ってください。 |
| **消耗品がフルフィルメントされていない** | PlayFab は引き換え後に開発者管理の消耗品を自動的にフルフィルメントします。消耗品が一度引き換えられたのに再度引き換えられない場合は、`RedeemMicrosoftStoreInventoryItems` の呼び出しを再試行してください。問題が続く場合は、サポート チャネルを通じて PlayFab チームにエスカレーションしてください。[Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds) を参照してください。 |
| **サンドボックスの不一致** | アドオンが、テストしている同じサンドボックスに公開されていることを確認してください。XBOX トークンはサンドボックス コンテキストを持つため、両方が一致する必要があります。 |
| **無効な XBOX トークン** | トークンが正しいパラメーターで取得されていることを確認してください: メソッド `POST`、URL `https://playfabapi.com/`、空のボディ文字列 `""`。 |
| **プレイヤーが XBOX ID で認証されていない** | プレイヤーは XBOX Live ID (たとえば `LoginWithXbox` 経由) を使用して PlayFab にサインインしている必要があります。他の ID タイプには引き換えに必要な XBOX コンテキストがありません。 |
API が HTTP エラー (400 など) を返す場合は、次のコードのエラー レスポンスを確認してください。
| エラー コード | 説明 |
| --------------------------------- | ------------------------------------------------------------------ |
| `InvalidCatalogItemConfiguration` | PlayFab カタログでバンドルまたは Marketplace Mapping が誤って構成されています。 |
| `InvalidXboxLiveToken` | XBOX トークンが無効、期限切れ、または誤ったパラメーターで取得されています。 |
| `AccountNotLinked` | プレイヤーの PlayFab アカウントが XBOX Live ID にリンクされていません。 |
| `XboxInaccessible` | PlayFab が XBOX サービスに到達できません。エラーは一時的な可能性があります。 |
| `XboxXASSExchangeFailure` | XSTS トークンの交換に失敗しました。Business Partner と relying party の構成を確認してください。 |
呼び出しが成功 (HTTP 200) しても空の結果が返され、他のすべての構成が正しく見える場合は、最初に Product Group の構成を確認してください。Product Group のステップは最もよく見落とされるステップです。
## PC / Windows タイトルに関する注意
このチュートリアルでは、委任された XSTS トークン (`XboxToken` パラメーター経由で渡される) を使用する XBOX フローを扱います。**PC / Windows タイトル** の場合、Microsoft は代わりに Microsoft Entra ID と共に User Store ID を使用したサービス間認証を推奨しています。詳細については、[Requesting a User Store ID for service-to-service authentication](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-requesting-a-userstoreid) および [Authenticating your service — User Store IDs](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-authenticating-your-service#authenticating-through-microsoft-entra-id-and-user-store-ids) を参照してください。
## 関連項目
* [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)
* [Authenticating your service (XSTS tokens)](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-authenticating-your-service)
* [Choosing the right product type](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-choosing-the-right-product-type)
* [Consumable-based ecosystems](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/fundamentals/xstore-consumable-based-ecosystems)
* [Managing consumables and refunds](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds)
* [Alternate ID (Marketplace Mapping)](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids)
* [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
- [マーケットプレイス統合 - 概要](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/overview.md)
- [マーケットプレイス統合 - Apple](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/apple.md)
- [マーケットプレイス統合 - Steam](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/steam.md)
- [Microsoft Store マーケットプレイスでの引き換え](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/microsoft.md)
- [マーケットプレイス統合 - Google](/ja-jp/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/google.md)