XUser オブジェクトのアカウントに紐付けられます。PC 上では、この ID は Microsoft Store アプリにサインインし購入に使用されているアカウントに紐付けられます。
PC では、Microsoft Store アプリと XBOX Live にサインインしゲームをプレイしているアカウント間で、アカウントの ID が異なる場合があります。
- Microsoft Store Collections サービスで認証する User Collections ID
- Microsoft Store Purchase サービスで認証する User Purchase ID
- Microsoft Entra ID アプリケーションを構成する。
- Microsoft Entra アプリケーション ID をパートナー センターのクライアント アプリに関連付ける。
- サービスで、発行元 ID を表す Microsoft Entra ID アクセス トークンを作成する。
- ゲームで、ユーザーの ID を表すユーザー Store ID キーを作成し、このキーをサービスに返す。
- Microsoft Store API へのリクエストを認証する。
- 有効期限が切れたらユーザー Store ID キーを更新する。
- サービス: Microsoft Entra アクセス トークンを作成し Store API を呼び出すセキュアなバックエンド。
- ゲーム: サインインしているユーザー用にユーザー Store ID キーを作成し、それらをサービスに渡すクライアント。
Microsoft.StoreServices .NET ライブラリとサンプル
統合を効率化するために、GitHub の Microsoft.StoreServices を使用してください。このライブラリは認証とキーのフローを処理し、Store サービス呼び出しのラッパーを提供します。サンプルには、消費型、返金の照合、およびキー更新のためのエンドツーエンドのパターンが含まれています。手順 1: Microsoft Entra ID アプリケーションを構成する
Microsoft Store API を使用する前に、API を呼び出す際にサービスを識別する Microsoft Entra Web アプリケーションを作成します。登録された Web アプリから、テナント ID、アプリケーション ID、およびシークレット キーを取得し、以降の手順で必要なアクセス トークンを生成します。Web アプリのテナント ID、アプリケーション ID、およびシークレット キーは、発行元下の複数のゲームや製品にわたって再利用できます。各ゲームで新しいものを作成する必要はありません。
- まだの場合は、クイックスタート: Microsoft ID プラットフォームにアプリケーションを登録するの手順に従って、Microsoft Entra ID に Web app / API アプリケーションを登録してください。
[!NOTE] アプリケーションを登録するときは、アプリケーションの種類として Web app / API を選択してください。この種類により、アプリケーションのキー (クライアント シークレット とも呼ばれる) を取得できます。Microsoft Store API を呼び出すには、後の手順で Microsoft Entra ID からアクセス トークンを要求するときにクライアント シークレットを提供する必要があります。
- Azure 管理ポータルで、Microsoft Entra ID に移動します。左側のペインでディレクトリ、[アプリの登録]、およびアプリケーションを選択します。
- 後で使用するために [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] の値をコピーします。
- 左側のペインの [証明書とシークレット] から新しいクライアント シークレットを作成してコピーします。
手順 2: Microsoft Entra アプリケーション ID をパートナー センターのクライアント アプリに関連付ける
- パートナー センターにサインインし、ゲームを選択します。
- [サービス] > [製品コレクションおよび購入] を選択します。使用可能な [Client ID] フィールドの 1 つに Microsoft Entra アプリケーション ID を入力します。
- [保存] を選択します。
- ゲームとそのアドオンを Store に再公開します。
アドオン製品は、親ゲームの [製品コレクションおよび購入] ページに保存された Client ID を継承します。ゲーム バンドル製品には、Client ID を追加する必要のある独自の [製品コレクションおよび購入] ページがあります。
手順 3: Microsoft Entra ID アクセス トークンの作成
すべての API リクエストには、認可ヘッダーにサービス アクセス トークンとして知られる Bearer トークンが必要です。必要なもう 1 つのアクセス トークンは、呼び出すサービスまたは API によって異なります。Microsoft Entra ID アクセス トークンは、アプリではなくサービスのコンテキスト内でのみ作成してください。クライアント シークレットをアプリに送信すると、漏洩する可能性があります。
異なるアクセス トークンとオーディエンス URI について
各アクセス トークンは、作成時に使用される異なるオーディエンス URI に関連付けられています。https://onestore.microsoft.com/.default のオーディエンスを使用するサービス アクセス トークンをクライアントに送信しないでください。サービス内で安全に保管してください。アクセス トークンの作成
アクセス トークンを作成するには、サービスで OAuth 2.0 API を使用します。Microsoft ID プラットフォームと OAuth 2.0 クライアント資格情報フローの手順に従って、https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token エンドポイントに HTTP POST を送信します。以下の例は、リクエストのサンプルを示しています。
client_idとclient_secretを Azure 管理ポータルのアプリ登録の値に設定します。- 必要なトークン タイプのオーディエンス URI に
resourceを設定します。異なるアクセス トークンとオーディエンス URI についてを参照してください。
手順 4: ユーザー Store ID キーを作成する
リクエスト内でユーザーを識別するために、サービスはユーザー Store ID キーを取得します。ユーザー Store ID は、User Collections ID または User Purchase ID のいずれかを指す一般的な用語として使用されます。これらのキー間の唯一の違いは、どの対応するサービスで認証できるかです。 ユーザー Store ID キーは、GDK API を使用してクライアント上で、またはサービス上で生成できます。このセクションでは、GDK API を通じてクライアント上でユーザー Store ID キーを作成することに焦点を当てます。サービス上でユーザー Store ID キーを生成する方法の詳細については、X-Token または OAuth 2.0 を使用したサービスからのユーザー Store ID の要求を参照してください。 ユーザー Store ID キーは、Microsoft Store アプリにサインインしているユーザーを表す JSON Web Token (JWT) です。このキーのクレームの詳細については、ユーザー Store ID キーのクレームを参照してください。各ユーザー Store ID キーは 30 日間有効です。サービスは、有効期限が切れる前にキーを更新できます。ユーザーのエンタイトルメントを照会するために継続的なアクセスがサービスに必要な場合は、新しいものを作成するのではなく Microsoft Store ID キーを更新してください。詳細については、ユーザー Store ID キーを更新するを参照してください。
Microsoft Store Collections サービス用の User Collections ID キーを作成するには
User Collections ID キーを使用すると、ユーザーが所有する製品を照会し、Collections API を使用して消費型製品を管理できます。消費型管理の詳細については、サービスから消費型製品を管理するを参照してください。- 手順 3 で作成した Collections アクセス トークンをゲームに渡します。
- ゲームで、XStoreGetUserCollectionsIdAsync を呼び出して User Collections ID キーを取得します。Collections アクセス トークンを
serviceTicketパラメーターとして渡します。オプションで内部ユーザー識別子をpublisherUserIdとして渡します。 - アプリが User Collections ID キーを正常に作成した後、キーをサービスに返します。
Microsoft Store Purchase サービス用の User Purchase ID キーを作成するには
User Purchase ID キーを使用すると、ユーザーが所有する製品を照会し、Purchase API を使用して消費型製品を管理できます。消費型管理の詳細については、サービスから消費型製品を管理するを参照してください。- 手順 3 で作成した Purchase アクセス トークンをゲームに渡します。
- ゲームで、XStoreGetUserPurchaseIdAsync を呼び出して User Purchase ID キーを取得します。Purchase アクセス トークンを
serviceTicketパラメーターとして渡します。オプションで内部ユーザー識別子をpublisherUserIdとして渡します。 - アプリが User Purchase ID キーを正常に作成した後、キーをサービスに返します。
手順 5: Microsoft Store API への呼び出しを認証する
手順については、Microsoft Entra ID とユーザー Store ID を使用した認証を参照してください。手順 6: 期限切れのユーザー Store ID キーを更新する
手順については、ユーザー Store ID キーを更新するを参照してください。追加情報
ユーザー Store ID キーを作成する図
次の図は、ユーザー Store ID キーを作成するプロセスを示しています。ユーザー Store ID キーのクレーム
ユーザー Store ID キーは、製品所有情報にアクセスしたいユーザーの ID を表す JWT です。Base64 でデコードすると、ユーザー Store ID キーには次の表に示すクレームが含まれます。
以下の例は、デコードされたユーザー Store ID ヘッダーを示しています。
kid クレームは、クライアントおよびタイトル サービス内では不透明な値として扱ってください。Store API が署名を検証します。
デコードされたユーザー Store ID クレーム セットの例。