XUser 物件的帳戶。在 PC 上，此身分識別會繫結至登入 Microsoft Store 應用程式並用於購買的帳戶。
在 PC 上，Microsoft Store 應用程式的帳戶身分識別可能與登入 XBOX Live 並遊玩遊戲的帳戶不同。
- User Collections ID，用於向 Microsoft Store Collections 服務進行驗證
- User Purchase ID，用於向 Microsoft Store Purchase 服務進行驗證
- 設定 Microsoft Entra ID 應用程式。
- 在 Partner Center 中將您的 Microsoft Entra 應用程式識別碼與用戶端應用程式建立關聯。
- 在您的服務中，建立代表您發行者身分識別的 Microsoft Entra ID 存取權杖。
- 在您的遊戲中，建立代表使用者身分識別的 User Store ID 金鑰，並將此金鑰傳回您的服務。
- 驗證對 Microsoft Store API 的要求。
- 在 User Store ID 金鑰到期時更新金鑰。
- 您的服務： 安全的後端，負責建立 Microsoft Entra 存取權杖並呼叫 Store API。
- 您的遊戲： 用戶端，負責為已登入的使用者建立 User Store ID 金鑰並將其傳遞給您的服務。
Microsoft.StoreServices .NET 程式庫和範例
若要簡化整合，請使用 GitHub 上的 Microsoft.StoreServices。此程式庫會處理驗證和金鑰流程，並提供 Store 服務呼叫的包裝函式。範例包含消耗性產品、退款對帳及金鑰更新的端對端模式。步驟 1：設定 Microsoft Entra ID 應用程式
在使用 Microsoft Store API 之前，請建立 Microsoft Entra Web 應用程式，以便在呼叫 API 時識別您的服務。從已註冊的 Web 應用程式取得租用戶識別碼、應用程式識別碼和祕密金鑰，以便在後續步驟中產生所需的存取權杖。您可以在發行者底下的多個遊戲和產品之間重複使用 Web 應用程式的租用戶識別碼、應用程式識別碼和祕密金鑰。您不需要為每個遊戲建立新的應用程式。
- 如果您尚未這麼做，請依照快速入門：向 Microsoft 身分識別平台註冊應用程式中的指示，向 Microsoft Entra ID 註冊 Web 應用程式 / API 應用程式。
[!NOTE] 註冊應用程式時，請選擇 Web 應用程式 / API 作為應用程式類型。此類型可讓您擷取應用程式的金鑰 (也稱為_用戶端密碼_)。若要呼叫 Microsoft Store API，您必須在後續步驟中向 Microsoft Entra ID 要求存取權杖時提供用戶端密碼。
- 在 Azure 管理入口網站中，前往 Microsoft Entra ID。選取您的目錄，在左窗格中選取 App registrations，然後選取您的應用程式。
- 複製 Application (client) ID 和 Directory (tenant) ID 值以供稍後使用。
- 在左窗格的 Certificates & Secrets 下建立並複製新的用戶端密碼。
步驟 2：在 Partner Center 中將您的 Microsoft Entra 應用程式識別碼與用戶端應用程式建立關聯
- 登入 Partner Center，然後選取您的遊戲。
- 選取 Services > Product collections and purchases。在其中一個可用的 Client ID 欄位中輸入您的 Microsoft Entra 應用程式識別碼。
- 選取 Save。
- 將遊戲及其附加元件重新發佈至市集。
附加元件產品會繼承儲存在其父遊戲 Product collections and purchases 頁面中的用戶端識別碼。遊戲組合產品有自己的 Product collections and purchases 頁面，您需要在該頁面中新增用戶端識別碼。
步驟 3：建立 Microsoft Entra ID 存取權杖
所有 API 要求都需要在 Authorization 標頭中提供持有人權杖，稱為服務存取權杖。所需的其他存取權杖取決於您所呼叫的服務或 API。請只在您的服務內容中建立 Microsoft Entra ID 存取權杖，而不要在您的應用程式中建立。如果您將用戶端密碼傳送至應用程式，可能會導致密碼外洩。
了解不同的存取權杖和對象 URI
每個存取權杖都與建立它時所使用的不同對象 URI 相關聯。切勿將使用
https://onestore.microsoft.com/.default 對象的服務存取權杖傳送至用戶端。請將其安全地儲存在您的服務中。建立存取權杖
若要建立存取權杖，請在您的服務中使用 OAuth 2.0 API。依照 Microsoft 身分識別平台和 OAuth 2.0 用戶端認證流程中的指示，將 HTTP POST 傳送至https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token 端點。下列範例顯示範例要求。
- 將
client_id和client_secret設定為 Azure 管理入口網站中的應用程式註冊值。 - 將
resource設定為您所需權杖類型的對象 URI。請參閱了解不同的存取權杖和對象 URI。
步驟 4：建立 User Store ID 金鑰
為了在要求中識別使用者，您的服務會取得 User Store ID 金鑰。User Store ID 是 User Collections ID 或 User Purchase ID 的通稱。這兩種金鑰之間唯一的差異在於它們可以向哪個對應的服務進行驗證。 您可以使用 GDK API 在用戶端上產生 User Store ID 金鑰，也可以在您的服務上產生。本節著重於透過 GDK API 在用戶端上建立 User Store ID 金鑰。如需如何在您的服務上產生 User Store ID 金鑰的詳細資訊，請參閱使用 X-token 或 OAuth 2.0 從您的服務要求 User Store ID。 User Store ID 金鑰是代表登入 Microsoft Store 應用程式之使用者的 JSON Web 權杖 (JWT)。如需此金鑰中宣告的詳細資訊，請參閱 User Store ID 金鑰中的宣告。每個 User Store ID 金鑰的有效期為 30 天。您的服務可以在金鑰到期之前更新金鑰。如果您的服務需要持續存取以查詢使用者的權利，請更新您的 Microsoft Store ID 金鑰，而不是建立新的金鑰。如需詳細資訊，請參閱更新 User 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 和 User Store ID 進行驗證。步驟 6：在 User Store ID 金鑰到期時更新金鑰
如需指示，請參閱更新 User Store ID 金鑰。其他資訊
建立 User Store ID 金鑰的圖表
下圖說明建立 User Store ID 金鑰的程序。
User Store ID 金鑰中的宣告
User Store ID 金鑰是 JWT，代表您要存取其產品擁有權資訊之使用者的身分識別。使用 Base64 解碼時，User Store ID 金鑰包含下表所示的宣告。
下列範例顯示已解碼的 User Store ID 標頭。
kid 宣告視為不透明值。Store API 會驗證簽章。
已解碼的 User Store ID 宣告集範例。