管理服務的產品權利

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

這些 API 由 REST 方法組成，其設計主要供開發人員搭配受跨平台服務支援的附加元件目錄使用。 這些 API 讓您能執行下列作業：

• Microsoft Store 集合 API： 查詢使用者 所擁有的產品，並把 消耗性產品報告為已履行。
• Microsoft Store 購買 API： 向使用者授予免費產品、 為使用者取得訂閱、以及 變更使用者的訂閱帳單狀態。

注意

Microsoft Store 集合 API 和購買 API 會使用 Azure Active Directory（Azure AD）驗證來存取客戶擁有權資訊。 如欲使用這些 API，您（或貴組織）必須擁有 Azure AD 目錄，而且您必須具有該目錄的全域管理員權限。 如果您已經使用 Microsoft 365 或 Microsoft 的其他商務服務，則您已有 Azure AD 目錄。

Microsoft.StoreServices 程式庫

如欲協助簡化驗證流程並呼叫 Microsoft Store Services，請檢閱 Github 上的 Microsoft.StoreServices 專案和範例。 Microsoft.StoreServices 程式庫會協助管理驗證金鑰，並提供包裝函式 API 來呼叫 Microsoft Store Services 來管理產品。 範例專案會強調服務如何使用 Microsoft.StoreServices 程式庫、管理消耗性產品的邏輯範例、協調退貨、更新過期的認證等等。 範例隨附逐步設定指南，以在您的電腦上或透過 Azure 設定範例服務。

• Microsoft.StoreServices 程式庫 (GitHub)
• Microsoft.StoreServices 範例 （GitHub）

概觀

下列步驟說明了使用 Microsoft Store 集合 API 和購買 API 的端對端流程：

1. 在 Azure AD 設定應用程式。
2. 把 Azure AD 應用程式識別碼跟您在合作夥伴中心的應用程式產生關聯。
3. 在您的服務中， 建立代表發行者身分識別的 Azure AD 存取權杖 。
4. 在您的用戶端 Windows 應用程式中， 建立代表目前使用者的身分識別的 Microsoft Store 識別碼金鑰 ，並把此金鑰傳回您的服務。

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

• 您的服務。 這是一個可在商務環境中安全執行的應用程式，而且可以使用您選擇的任何開發平台進行實作。 您的服務負責建立案例所需的 Azure AD 存取權杖，以及呼叫 Microsoft Store 集合 API 和購買 API 的 REST URI。
• 您的用戶端 Windows 應用程式。 這是您想要存取和管理客戶權利資訊的應用程式（包括應用程式的附加元件）。 此應用程式負責建立您從您服務上呼叫 Microsoft Store 集合 API 及購買 API 所需要的 Microsoft Store ID 金鑰。

第 1 步驟：在 Azure AD 設定應用程式。

您必須先建立 Azure AD Web 應用程式、擷取應用程式的租用戶識別碼和應用程式識別碼，並產生金鑰後，才能使用 Microsoft Store 集合 API 或購買 API。 Azure AD Web 應用程式代表您想用於呼叫 Microsoft Store 集合 API 或購買 API 的服務。 您需要租用戶識別碼、應用程式識別碼和金鑰，才能產生您呼叫 API 所需要的 Azure AD 存取權杖。

1. 如果您尚未這麼做，請遵循把應用程式跟 Azure Active Directory 整合 中的指示，向 Azure AD 註冊 Web 應用程式/API 應用程式。

   注意

   當您註冊應用程式時，您必須選擇 [Web 應用程式/ API ] 作為應用程式類型，以便讓您能擷取應用程式的金鑰（也稱為 客戶端密碼）。 如欲呼叫 Microsoft Store 集合 API 或購買 API，您在稍後的步驟中向 Azure AD 要求存取權杖時必須提供客戶端密碼。

2. 在 Azure 管理入口網站中，導覽至 [Azure Active Directory]。 選取您的目錄，按一下左側導覽窗格中的 [應用程式註冊]，然後選取您的應用程式。

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

4. 建立您稍後需要的金鑰（全都稱為 客戶端密碼）。 在左窗格中，按一下 [設定]，然後按一下 [金鑰]。 在此頁面上，完成建立 金鑰的步驟。 複製此金鑰供日後使用。

第 2 步驟：把 Azure AD 應用程式識別碼與您在合作夥伴中心的用戶端應用程式產生關聯

您必須先把 Azure AD 應用程式識別碼跟合作夥伴中心內的應用程式（或包含附加元件的應用程式）產生關聯後，才可以使用 Microsoft Store 集合 API 或購買 API 來為您的應用程式或附加元件設定應用程式的擁有權。

注意

您只需要執行此工作一次。 當您擁有租用戶識別碼、應用程式識別碼、及客戶端密碼後，您可以隨時重複使用這些值，以建立新的 Azure AD 存取權杖。

1. 登入合作夥伴中心，並選取您的應用程式。
2. 前往 [服務>產品集合和購買] 頁面，並把您的 Azure AD 應用程式識別碼輸入到其中一個可用的 [用戶端識別碼] 欄位。

第 3 步驟：建立 Azure AD 存取權杖

您的服務必須先建立數個代表您發行者身分識別的不同 Azure AD 存取權杖，您才能擷取 Microsoft Store 識別碼金鑰或呼叫 Microsoft Store 集合 API 或購買 API。 每個權杖都會搭配不同的 API 使用。 每個權杖的存留期為 60 分鐘，您可以在權杖到期後重新整理。

重要

只在服務的內容中建立 Azure AD 存取權杖，而不是在您的應用程式中。 如果客戶端密碼傳送至您的應用程式，可能會遭到洩漏。

瞭解不同的權杖和對象 URI

取決於您想要在 Microsoft Store 集合 API 或購買 API 中呼叫的方法，您必須建立兩個或三個不同的權杖。 每個存取權杖都會跟不同的對象 URI 相關聯。

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

  重要

  僅搭配 https://onestore.microsoft.com 安全儲存在服務內的存取權杖使用對象。 在服務外部公開此對象的存取權杖，可能會讓您的服務容易受到重新執行攻擊。

• 如果您想要在 Microsoft Store 集合 API 中呼叫方法以查詢使用者 所擁有的產品，或 把消耗性產品報告為已履行，您也必須使用 https://onestore.microsoft.com/b2b/keys/create/collections 對象 URI 建立權杖。 在稍後步驟中，您會把此權杖傳遞至 Windows SDK 中的用戶端方法，以要求可與 Microsoft Store 集合 API 搭配使用的 Microsoft Store 識別碼金鑰。

• 如果您想要在 Microsoft Store 購買 API 中呼叫方法，以便向使用者授予免費產品、 為使用者取得訂閱、或 變更使用者的訂閱帳單狀態，您也必須使用https://onestore.microsoft.com/b2b/keys/create/purchase對象 URI 建立權杖。 在稍後步驟中，您會把此權杖傳遞至 Windows SDK 中的用戶端方法，以要求可與 Microsoft Store 購買 API 搭配使用的 Microsoft Store 識別碼金鑰。

建立權杖

如要建立存取權杖，請依照[服務對服務呼叫使用客戶端認證]中的指示，在服務中使用 OAuth 2.0 API，以便向https://login.microsoftonline.com/<tenant_id>/oauth2/token端點寄出 HTTP POST。 以下是範例要求。

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 Store 識別碼金鑰

您的應用程式必須先建立 Microsoft Store 識別碼金鑰並傳送至您的服務後，您才能呼叫 Microsoft Store 集合 API 或購買 API 中的任何方法。 此金鑰是 JSON Web 權杖（JWT），代表您想要存取其產品擁有權資訊的使用者身分識別。 如需此金鑰中宣告的詳細資訊，請參閱 Microsoft Store 識別碼金鑰中的宣告。

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

注意

每個 Microsoft Store 識別碼金鑰的有效期限為 90 天。 金鑰到期之後，您可以更新金鑰。 建議您更新 Microsoft Store 識別碼金鑰，而不是建立新的金鑰。

要建立 Microsoft Store 集合 API 的 Microsoft Store 識別碼金鑰

請遵循下列步驟來建立 Microsoft Store 識別碼金鑰，以便與 Microsoft Store 集合 API 搭配使用，以查詢使用者 所擁有的產品，或 把消耗性產品報告為已履行。

1. 把具有對象 URI 值的 https://onestore.microsoft.com/b2b/keys/create/collections Azure AD 存取權杖從您的服務傳遞至用戶端應用程式。 這是您在稍早 在步驟 3建立的其中一個權杖。

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

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

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

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

3. 在您的應用程式成功建立 Microsoft Store 識別碼金鑰之後，請把金鑰傳回您的服務。

要建立 Microsoft Store 購買 API 的 Microsoft Store 識別碼金鑰

請遵循下列步驟，建立您可以與 Microsoft Store 購買 API 搭配使用的 Microsoft Store 識別碼金鑰，以便向使用者授予免費產品、為使用者取得訂閱、或 變更使用者的訂閱帳單狀態。

1. 把具有對象 URI 值的 https://onestore.microsoft.com/b2b/keys/create/purchase Azure AD 存取權杖從您的服務傳遞至用戶端應用程式。 這是您在稍早 在步驟 3建立的其中一個權杖。

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

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

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

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

3. 在您的應用程式成功建立 Microsoft Store 識別碼金鑰之後，請把金鑰傳回您的服務。

圖表

下圖說明了建立 Microsoft Store 識別碼金鑰的流程。

Microsoft Store 識別碼金鑰中的宣告

Microsoft Store 識別碼金鑰是 JSON Web 權杖（JWT），代表您想要存取其產品擁有權資訊的使用者身分識別。 使用 Base64 解碼時，Microsoft Store 識別碼金鑰會包含下列宣告。

• iat：識別金鑰核發的時間。 此宣告可用來判斷權杖的存留期。 此值以紀元時間表示。
• iss：識別簽發者。 這與宣告具有相同的值 aud 。
• aud：識別對象。 必須是下列其中一個值：https://collections.mp.microsoft.com/v6.0/keys或https://purchase.mp.microsoft.com/v6.0/keys 。
• exp：識別到期時間，亦即到了該時間後，除非更新金鑰，否則即不再接受用該金鑰處理任何事務。 此宣告的值會以紀元時間表示。
• nbf：識別可接受權杖進行處理的時間。 此宣告的值會以紀元時間表示。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId：用於識別開發人員的用戶端識別碼。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload：包含僅供 Microsoft Store 服務使用的資訊的不透明承載（加密和 Base64 編碼）。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId：識別您服務內容中目前使用者的使用者識別碼。 這是您傳入您用來建立金鑰之方法的選擇性 publisherUserId 參數中的相同值。
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri：可用來更新金鑰的 URI。

以下是已解碼的 Microsoft Store 識別碼金鑰標頭範例。

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

以下是已解碼的 Microsoft Store 識別碼金鑰宣告集範例。

{
    "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": 1442395542,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1450171541,
    "nbf": 1442391941
}

相關主題

• 查詢產品
• 把消耗品報告為已履行
• 免費授予產品
• 取得使用者訂閱
• 變更使用者訂閱的帳單狀態
• 更新 Microsoft Store 識別碼金鑰
• 把應用程式跟 Azure Active Directory 整合
• 了解 Azure Active Directory 應用程式資訊清單
• 支援的權杖和宣告類型
• Microsoft.StoreServices 程式庫 (GitHub)