從服務管理產品使用權限

如果您有應用程式和附加元件目錄，您可以使用 Microsoft Store 集合 API 和 Microsoft Store 購買 API，從您的服務存取這些產品的權利資訊。 授權 代表客戶有使用透過 Microsoft Store 發佈的應用程式或附加元件的權利。

這些 API 是由設計為供開發人員搭配跨平臺服務支援的附加元件目錄使用的 REST 方法所組成。 這些 API 可讓您執行下列動作：

• Microsoft市集集合 API：使用者 擁有的產品查詢，並 將消費性產品回報為已完成。
• Microsoft市集購買 API：將免費產品授與使用者、取得使用者的訂閱，變更使用者訂閱的計費狀態。

備註

Microsoft市集集合 API 和購買 API 會使用 Microsoft 身分識別平臺 （Entra ID） 驗證來存取客戶擁有權資訊。 若要使用這些 API，您（或貴組織）必須具有 Entra ID 租使用者，而且您必須 擁有租使用者的全域系統管理員 許可權。 如果您已經使用 Microsoft 的 Microsoft 365 或其他商務服務，您就已經有 Entra ID 租戶。

Microsoft.StoreServices 程式庫

若要協助簡化驗證流程並呼叫 Microsoft 市集服務，請檢閱 Github 上的 Microsoft.StoreServices 專案和範例。 Microsoft.StoreServices 連結庫可協助管理驗證密鑰，並提供包裝函式 API 來呼叫 Microsoft Store Services 來管理產品。 範例專案展示如何服務可以使用 Microsoft.StoreServices 程式庫，示範管理消費性產品的邏輯、對帳已退款的購買、更新過期的憑證等等。 範例附帶逐步設定指南，用於在您的電腦上或透過 Azure 設定範例服務。

• Microsoft.StoreServices 函式庫（GitHub）
• Microsoft.StoreServices 範例 （GitHub）

概述

下列步驟描述使用 Microsoft Store 集合 API 和購買 API 的整體流程：

1. 在 Entra ID中設定應用程式。
2. 在合作夥伴中心將 Entra ID 應用程式識別碼與您的應用程式關聯。
3. 在您的服務中，建立代表您的發行者身份的 Entra ID 存取令牌。
4. 在您的用戶端 Windows 應用程式中，建立Microsoft市集標識符密鑰，此金鑰代表目前使用者的身分識別，並將此金鑰傳回您的服務。

此端對端程式牽涉到執行不同工作的兩個軟體元件：

• 您的服務。 這是一個應用程式，可在商務環境的內容中安全地執行，而且可以使用您選擇的任何開發平臺來實作。 您的服務負責建立情境所需的 Entra ID 存取令牌，並呼叫 Microsoft 商店集合 API 和購買 API 的 REST URI。
• 您的用戶端應用程式。 這是您想要存取和管理客戶權利資訊的應用程式（包括應用程式的附加元件）。 此應用程式負責建立 Microsoft Store ID 金鑰，您必須呼叫 Microsoft Store 集合 API，並從您的服務呼叫購買 API。

步驟 1：在 Entra ID 中設定應用程式

您必須先建立 Entra ID Web 應用程式、擷取應用程式的租使用者標識碼和應用程式標識碼，併產生密鑰，才能使用 Microsoft Store 集合 API 或購買 API。 Entra ID Web 應用程式代表您要從中呼叫 Microsoft Store 集合 API 或購買 API 的服務。 您需要租使用者標識碼、應用程式識別碼和密鑰，才能產生您需要呼叫 API 的 Entra ID 存取令牌。

1. 如果您尚未這麼做，請遵循 快速入門中的指示：使用 Microsoft 身分識別平台註冊應用程式，以使用 Entra ID 註冊 Web 應用程式/API 應用程式。

   注意

   當您註冊應用程式時，您必須選擇 Web 應用程式/API 作為應用程式類型，以便擷取應用程式的金鑰（也稱為 用戶端密碼）。 若要呼叫 Microsoft Store 集合 API 或購買 API，您必須在稍後的步驟中向 Entra ID 要求存取令牌時提供客戶端密碼。

2. 在 Azure 管理入口中，導航至 Microsoft Entra ID。 選取您的租使用者，按下左側瀏覽窗格中的 [管理] [應用程式註冊]，然後選取您的應用程式。

3. 系統會帶您前往應用程式的主要註冊頁面。 在此頁面上，複製 應用程式識別碼 值以供稍後使用。

4. 建立稍後將需要的密鑰（這全稱為 客戶端密碼）。 在左窗格中，點擊「設定」，然後「金鑰」。 在此頁面上，完成建立金鑰的步驟 。 複製此金鑰以供稍後使用。

步驟 2：將 Entra ID 應用程式識別碼與合作夥伴中心內的用戶端應用程式產生關聯

您必須先將 Entra 應用程式識別碼與合作夥伴中心的應用程式（或包含附加元件的應用程式）建立關聯，才能使用 Microsoft Store 集合 API 或購買 API 來設定應用程式或附加元件擁有權和購買。

注意

您只需要執行此工作一次。 在您擁有租使用者識別碼、應用程式識別碼和用戶端密碼之後，您可以隨時重複使用這些值，以建立新的 Entra ID 存取令牌。

1. 登入 合作夥伴中心，然後選取您的應用程式。
2. 移至 [Services>產品集合和購買] 頁面，然後將您的 Entra 應用程式識別符輸入其中一個可用的 用戶端識別符 字段。

步驟 3：建立 Entra ID 存取令牌

在您能擷取 Microsoft 市集 ID 金鑰或呼叫 Microsoft 市集集合 API 及購買 API 之前，您的服務必須先建立數個不同的 Entra ID 存取令牌，以代表發行商的身分識別。 每個令牌都會搭配不同的 API 使用。 每個令牌的存留期為 60 分鐘，您可以在令牌到期後加以重新整理。

重要

只在服務內容中建立 Entra ID 存取令牌，而不是在應用程式中建立。 如果客戶端密碼傳送至您的應用程式，可能會遭到入侵。

瞭解不同的令牌和受眾 URI

根據您要呼叫的 Microsoft Store 集合 API 或購買 API 的方法，您必須創建兩到三個不同的令牌。 每個存取令牌都會與不同的受眾 URI 相關聯。

• 在所有情況下，您必須使用 https://onestore.microsoft.com 受眾 URI 建立令牌。 在稍後的步驟中，您會將此令牌傳遞至 Microsoft Store 集合 API 或購買 API 中方法的 授權 標頭。

  重要

  僅可搭配安全儲存在服務中的存取令牌使用 https://onestore.microsoft.com 受眾。 將此受眾的存取令牌公開到服務外部，可能會使您的服務容易受到重放攻擊。

• 如果您想要呼叫 Microsoft Store 集合 API 中的方法，以 查詢使用者 擁有的產品，或 將消費性產品回報為已完成，您也必須使用 https://onestore.microsoft.com/b2b/keys/create/collections 物件 URI 建立令牌。 在稍後的步驟中，您會將此令牌傳遞至 Windows SDK 中的用戶端方法，以請求可與 Microsoft Store 集合 API 搭配使用的 Microsoft Store ID 金鑰。

• 如果您想在 Microsoft 市集購買 API 中執行方法來 授予使用者免費產品、獲取使用者的訂用帳戶，或 更改使用者訂閱的計費狀態，您也必須使用 https://onestore.microsoft.com/b2b/keys/create/purchase 受眾 URI 建立令牌。 在稍後的步驟中，您會將此令牌傳遞至 Windows SDK 中的客戶端方法，以請求一個可與 Microsoft 市集購買 API 搭配使用的 Microsoft 市集識別碼密鑰。

建立令牌

若要建立存取令牌，請依照使用用戶端認證 服務對服務呼叫中的指示，使用客戶端認證 將 HTTP POST 傳送至 https://login.microsoftonline.com/<tenant_id>/oauth2/token 端點，以在服務中使用 OAuth 2.0 API。 以下是範例要求。

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://onestore.microsoft.com

針對每個代幣，指定下列參數資料：

• 針對 client_id 和 client_secret 參數，請針對您從 Azure 管理入口網站擷取的應用程式指定應用程式識別碼和客戶端密碼。 這兩個參數都是必要參數，才能使用 Microsoft Store 集合 API 或購買 API 所需的驗證層級來建立存取令牌。

• 針對 資源 參數，請根據您所建立的存取權杖類型，指定前一節 所列的其中一個受眾 URI。

存取令牌過期之後，您可以依照此處的指示 刷新它。 如需存取權杖結構的詳細資訊，請參閱 支援的權杖和宣告類型。

步驟 4：建立Microsoft市集標識符密鑰

您的應用程式必須先建立 Microsoft Store ID 金鑰並將它傳送至您的服務，在您能夠呼叫 Microsoft Store 集合 API 或購買 API 中的任何方法之前。 此金鑰是 JSON Web 令牌 （JWT），代表您想要存取其產品擁有權資訊的使用者身分識別。 如需有關此金鑰中宣告的更多資訊，請參閱 Microsoft Store ID 金鑰中的 宣告。

目前，建立Microsoft市集標識符密鑰的唯一方法是從您 app 中的用戶端程式代碼呼叫通用 Windows 平臺 （UWP） API。 產生的金鑰代表目前登入裝置上Microsoft市集的使用者身分識別。

注意

每個 Microsoft 市集識別碼金鑰都有效 30 天。 金鑰到期之前，您可以 更新金鑰。 建議您更新您的 Microsoft 商店識別碼金鑰，而不是建立新的識別碼金鑰。

為 Microsoft Store 集合 API 建立 Microsoft Store 識別碼密鑰

請遵循下列步驟來建立可搭配 Microsoft Store 集合 API 使用的 Microsoft Store 標識符密鑰，以 查詢使用者 或 將消費性產品回報為已完成。

1. 將具有受眾 URI 值 https://onestore.microsoft.com/b2b/keys/create/collections 的 Entra ID 存取令牌，從您的服務傳遞至用戶端應用程式。 這是您在步驟 3稍早建立的其中一個代幣。

2. 在您的應用程式程式代碼中，呼叫下列其中一種方法來擷取Microsoft市集標識符密鑰：

• 如果您的 app 使用 Windows.Services.Store 命名空間中的 StoreContext 類別來管理應用程式內購買，請使用 StoreContext.GetCustomerCollectionsIdAsync 方法。

• 如果您的 app 使用 Windows.ApplicationModel.Store 命名空間中的 CurrentApp 類別來管理應用程式內購買，請使用 CurrentApp.GetCustomerCollectionsIdAsync 方法。

  將您的 Entra ID 存取令牌傳遞至 方法的 serviceTicket 參數。 如果您在您以目前應用程式發行者身分管理的服務內容中維護匿名使用者標識碼，您也可以將使用者標識碼傳遞至 publisherUserId 參數，將目前使用者與新的 Microsoft 市集標識符密鑰產生關聯（使用者標識符會內嵌在密鑰中）。 否則，如果您不需要將使用者標識碼與 Microsoft Store 識別符密鑰產生關聯，您可以將任何字串值傳遞至 publisherUserId 參數。

3. 當您的應用程式成功建立 Microsoft Store ID 金鑰後，將該金鑰傳回您的服務。

為 Microsoft Store 購買 API 建立 Microsoft Store ID 密鑰

請遵循下列步驟來建立Microsoft市集標識符密鑰，以便搭配 Microsoft 市集購買 API 使用，將免費產品授與使用者、取得使用者的訂用帳戶，或 變更使用者的訂用帳戶計費狀態。

1. 將具有受眾 URI 值 https://onestore.microsoft.com/b2b/keys/create/purchase 的 Entra ID 存取令牌，從您的服務傳遞至用戶端應用程式。 這是您在步驟 3稍早建立的其中一個令牌 。

2. 在您的應用程式程式代碼中，呼叫下列其中一種方法來擷取Microsoft市集標識符密鑰：

• 如果您的 app 使用 Windows.Services.Store 命名空間中的 StoreContext 類別來管理應用程式內購買，請使用 StoreContext.GetCustomerPurchaseIdAsync 方法。

• 如果您的 app 使用 Windows.ApplicationModel.Store 命名空間中的 CurrentApp 類別來管理應用程式內購買，請使用 CurrentApp.GetCustomerPurchaseIdAsync 方法。

  將您的 Entra ID 存取令牌傳遞至方法中的 serviceTicket 參數。 如果您在您以目前應用程式發行者身分管理的服務內容中維護匿名使用者標識碼，您也可以將使用者標識碼傳遞至 publisherUserId 參數，將目前使用者與新的 Microsoft 市集標識符密鑰產生關聯（使用者標識符會內嵌在密鑰中）。 否則，如果您不需要將使用者標識碼與 Microsoft Store 識別符密鑰產生關聯，您可以將任何字串值傳遞至 publisherUserId 參數。

3. 在應用程式成功建立 Microsoft Store ID 金鑰之後，請將該金鑰傳回您的服務。

圖表

以下圖表說明建立 Microsoft 應用程式商店 ID 金鑰的過程。

Microsoft 商店 ID 金鑰中的宣告

Microsoft 市集 ID 金鑰是 JSON Web 令牌（JWT），代表您想要存取產品擁有權資訊的使用者身分。 當使用Base64解碼時，一個Microsoft Store ID密鑰包含以下聲明。

• iat：識別發出金鑰的時間。 此宣告可用來確定令牌的年齡。 此值會以 Epoch 時間表示。
• iss：識別簽發者。 這與 aud 主張具有相同的值。
• aud：識別觀眾。 必須是下列其中一個值：https://collections.mp.microsoft.com/v6.0/keys 或 https://purchase.mp.microsoft.com/v6.0/keys。
• exp：識別到期時間，從該時間起，除非用於更新金鑰，否則金鑰將不再被接受來處理任何項目。 此宣告的值會以 epoch 時間表示。
• nbf：識別可以接受令牌以進行處理的時間。 此宣告的值會以 epoch（紀元起始）時間表示。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId：識別開發人員的用戶端標識碼。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload：一種不透明的資料包（經過加密和 Base64 編碼），其中包含僅供 Microsoft Store 服務使用的資訊。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId：識別您服務內容中目前用戶的使用者標識碼。 這是與您用來創建密鑰的 方法之可選 publisherUserId 參數相同的值。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri：可用來更新密鑰的 URI。

以下是一個解碼的 Microsoft Store ID 密鑰的標頭範例。

{
    "typ":"JWT",
    "alg":"RS256",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

以下是已解碼的 Microsoft Store ID 密鑰宣告集的範例。

{
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d5773695a3b44928227393bfef1e13d",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "ZdcOq0/N2rjytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQMLaYCrgtC0d/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
    "iat": 1733526889,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1733523289,
    "nbf": 1736118889
}

相關主題

• 查詢產品
• 將消費性產品回報為已完成
• 贈送免費產品
• 取得使用者訂用帳戶
• 變更使用者訂用帳戶的計費狀態
• 更新 Microsoft Store ID 金鑰
• 整合應用程式與Microsoft身分識別平臺
• Microsoft身分識別平臺中的 識別符令牌
• Microsoft.StoreServices 程式庫（GitHub）