私人供應項目提交 API 概觀

發行項
07/16/2024

私人供應專案可讓發行者和客戶透過使用自定義條款建立限時定價，在 Azure Marketplace 中交易一或多個產品。私人供應專案提交 API 可讓發行者以程式設計方式為客戶和/或 CSP 合作夥伴建立及管理私人供應專案。此 API 會使用 Microsoft Entra ID 來驗證來自您的應用程式或服務的呼叫。

合作夥伴中心提供三種主要類型的私人供應專案，並由私人供應專案提交 API 支援：

ISV 至客戶私人供應專案 – 也稱為合作夥伴中心的客戶私人供應專案。這是ISV與特定客戶之間的自定義交易，其中包含 Azure Marketplace 中特定產品的自定義條款和定價。深入瞭解 ISV給客戶私人供應專案。
ISV 至 CSP 合作夥伴私人供應專案 – 也稱為合作夥伴中心的 CSP 合作夥伴私人供應專案。這種類型的私人供應專案可讓ISV指定限時保證金，為其CSP合作夥伴建立批發價格。深入瞭解 ISV到 CSP 合作夥伴私人供應專案。
多方私人供應專案 （MPO） – ISV 與特定客戶慣用的通道合作夥伴共同設定的自定義交易，以及 Azure Marketplace 中特定產品的自定義條款和定價。 ISV 會定義提供給合作夥伴的折扣批發價格，然後通道合作夥伴可以在批發價格之上加上標記，以到達最終的客戶價格，並將供應專案提供給客戶接受和購買。接受和購買 MPO 遵循與 ISV 相同的流程，提供給客戶私人供應專案。深入瞭解多方私人供應專案。

詞彙

MPO 發起者 – MPO 是 ISV 與通道合作夥伴在針對特定客戶的相同自定義交易上共同作業，第一次建立 MPO 的方會指定供應專案的「贊助者」，通常是 MPO 中包含的產品的 ISV。任何指定的 MPO 只能有一個建立者。
MPO 賣方 – 以最終客戶價格準備供應專案的通道合作夥伴，並將供應專案提供給客戶是 MPO 的賣方。任何指定的 MPO 只能有一個賣方。
產品 – 代表 Azure Marketplace 中供應專案的單一單位。每個清單頁面有一個產品。
方案 – 特定產品的單一版本。給定產品可以有多個方案，這些方案代表各種定價或條款層級。
作業 – 在此 API 中提出要求時所建立的工作。使用此 API 來管理私人供應專案和多方私人供應專案時，會建立作業以完成要求。作業完成後，您可以取得相關（多方）私人供應專案的詳細資訊。

支援的案例

準備好使用此 API

在您撰寫程式代碼來呼叫私人供應專案 API 之前，請確定您已完成下列必要條件。所有發佈合作夥伴都適用相同的必要條件。

步驟 1：完成使用Microsoft產品擷取 API 的必要條件（一次性）

您或貴組織必須具有Microsoft Entra 目錄和全域管理員許可權。如果您已經從 Microsoft 使用 Microsoft 365 或其他商務服務，則您已經Microsoft Entra 目錄。如果沒有，您可以在合作夥伴中心免費建立新的Microsoft Entra 標識符。

您必須將Microsoft Entra ID 應用程式與您的合作夥伴中心帳戶產生關聯，並取得您的租用戶標識碼、用戶端標識符和密鑰。您需要這些值，才能取得您將在私人供應專案 API 呼叫中使用的Microsoft Entra 存取令牌。

步驟 2：取得Microsoft Entra 存取令牌（每次）

在呼叫 Microsoft 市集提交 API 中的任何方法之前，您需要Microsoft Entra 存取令牌，才能傳遞至 API 中每個方法的授權標頭。在令牌到期之前，您有 60 分鐘的時間可以使用令牌。到期之後，您可以重新整理令牌，以便在 API 的進一步呼叫中繼續使用令牌。

若要取得存取令牌，請參閱使用用戶端認證將 HTTP POST 傳送至 tenant_id>/oauth2/token 端點的服務https://login.microsoftonline.com/<對服務呼叫。以下是範例要求：

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://graph.microsoft.com/

針對 POST URI 和 client_id 和 client_secret 參數中的tenant_id值，請在上一節中指定您從合作夥伴中心擷取的應用程式租用戶識別碼、用戶端識別碼和密鑰。針對資源參數，您必須指定 https://graph.microsoft.com/。

尋找產品、方案和私人供應項目標識碼

識別碼	哪裡可以找到它們
client_id	請參閱將Microsoft Entra 應用程式與您的合作夥伴中心帳戶建立關聯。
tenant_id	請參閱將Microsoft Entra 應用程式與您的合作夥伴中心帳戶建立關聯。
client_secret	請參閱將Microsoft Entra 應用程式與您的合作夥伴中心帳戶建立關聯。
productId	請參閱本文中的擷取產品。
planId	請參閱本文中擷取特定產品的方案。
privateofferId	請參閱本文中的擷取私人供應專案。

擷取

私人供應專案是以合作夥伴中心帳戶中的現有產品為基礎。若要查看與您的合作夥伴中心帳戶相關聯的產品清單，請使用此 API 呼叫：

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

回應會以下列範例格式顯示：

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

擷取特定產品的方案

針對包含多個方案的產品，您可能想要根據一個特定方案建立私人供應專案。如果是，您需要該方案的標識碼。使用下列 API 呼叫取得產品的方案清單（例如變體或 SKU）：

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

回應會以下列範例格式顯示：

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

擷取私人供應專案

若要查看所有私人供應項目的清單，包括與您的帳戶相關聯的多方私人供應專案，請使用下列 API 呼叫：

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

如何使用 API

私人供應專案 API 可讓您在合作夥伴中心帳戶內建立及管理與產品和方案相關聯的私人供應專案。以下是使用此 API 時一般呼叫模式的摘要。

步驟 1：提出要求

當您進行 API 呼叫以建立、刪除、撤銷或升級私人供應專案時，會建立新的作業來完成所要求的工作。 API 回應包含與作業相關聯的jobId。

步驟 2：輪詢作業狀態

使用初始 API 回應中的 jobId，輪詢以取得作業狀態。作業的狀態會是 [執行中 ] 或 [已完成]。作業完成後，結果會是 [成功] 或 [失敗]。 若要避免效能問題，請勿每分鐘輪詢作業一次以上。

jobStatus	描述
未開始	作業尚未啟動;這是初始要求回應的一部分。
執行中	作業仍在執行中。
已完成	作業已完成。如需詳細資訊，請參閱 jobResult 。
jobResult	說明
待定	作業尚未完成。
成功	作業已順利完成。此作業也會傳回 resourceURI，此資源 URI 是指與作業相關的私人供應專案。使用此 resourceURI 來取得私人供應專案的完整詳細數據。
失敗	作業失敗。這也會傳回任何相關的錯誤，以協助判斷失敗的原因。

如需詳細資訊，請參閱查詢現有作業的狀態。

步驟 3：從已完成的工作取得資訊

成功的作業會傳回參考相關私人供應專案的 resourceUri。使用此資源 URI 來取得未來私人供應專案的詳細數據，例如 privateofferId。

失敗的作業包含錯誤，詳細說明作業失敗的原因，以及如何解決問題。

如需詳細資訊，請參閱取得現有私人供應專案的詳細數據。

ISV 和通道合作夥伴應如何共同使用 API 進行多方私人供應專案

ISV 和通道合作夥伴都可以使用相同的 API 來建立和管理指定的 MPO。不過，可能會影響 API 的 MPO 資源取決於 API 的呼叫者是 ISV（原始程式）還是 MPO 的通道夥伴（賣方）。管理合作夥伴中心的相同 ISV/通道合作夥伴發佈流程和商務規則會鏡像在 API 中。以下是概觀：

API 作業	ISV （發源者）	頻道合作夥伴（賣方）
建立	預期對像是發佈 API 呼叫時銷售合作夥伴（賣方），在通道合作夥伴提交之前，終端客戶不會看到私人供應專案可編輯的資源：有效日期預定受益者（客戶）在供應專案上共同作業的頻道合作夥伴，每個私人供應專案限製為1個要通知私人供應項目狀態的其他ISV聯繫人 ISV 自定義條款及條件私人供應專案中包含的產品/方案每個產品/方案的合約持續時間每個產品的包含數量（如果適用）非定價計劃屬性（如果適用）針對包含的產品/方案提供給通道合作夥伴的折扣批發價格 ISV 銷售注意事項	預期對像是張貼 API 呼叫時的終端客戶可編輯的資源：頻道合作夥伴自定義條款及條件準備者客戶調整（標記百分比）在私人供應專案中包含的每個產品/方案的ISV批發價格之上，這會決定最終的客戶價格其他頻道合作夥伴聯繫人，以收到私人供應項目狀態的通知頻道合作夥伴銷售注意事項
刪除	支援處於草稿狀態的私人供應專案	不支援
撤回	支援ISV所發佈的私人供應專案，但尚未由頻道合作夥伴發佈，或由通道合作夥伴撤銷	支援已發佈且可供終端客戶使用但尚未接受的私人供應專案

API 作業

ISV （發源者）

頻道合作夥伴（賣方）

建立

預期對像是發佈 API 呼叫時銷售合作夥伴（賣方），在通道合作夥伴提交之前，終端客戶不會看到私人供應專案

可編輯的資源：

有效日期
預定受益者（客戶）
在供應專案上共同作業的頻道合作夥伴，每個私人供應專案限製為1個
要通知私人供應項目狀態的其他ISV聯繫人
ISV 自定義條款及條件
私人供應專案中包含的產品/方案
每個產品/方案的合約持續時間
每個產品的包含數量（如果適用）
非定價計劃屬性（如果適用）
針對包含的產品/方案提供給通道合作夥伴的折扣批發價格
ISV 銷售注意事項

預期對像是張貼 API 呼叫時的終端客戶

可編輯的資源：

頻道合作夥伴自定義條款及條件
準備者
客戶調整（標記百分比）在私人供應專案中包含的每個產品/方案的ISV批發價格之上，這會決定最終的客戶價格
其他頻道合作夥伴聯繫人，以收到私人供應項目狀態的通知
頻道合作夥伴銷售注意事項

刪除

支援處於草稿狀態的私人供應專案

不支援

撤回

支援ISV所發佈的私人供應專案，但尚未由頻道合作夥伴發佈，或由通道合作夥伴撤銷

支援已發佈且可供終端客戶使用但尚未接受的私人供應專案

共用方式為

私人供應項目提交 API 概觀

詞彙

支援的案例

準備好使用此 API

步驟 1：完成使用Microsoft產品擷取 API 的必要條件（一次性）

步驟 2：取得Microsoft Entra 存取令牌（每次）

尋找產品、方案和私人供應項目標識碼

擷取

擷取特定產品的方案

擷取私人供應專案

如何使用 API

步驟 1：提出要求

步驟 2：輪詢作業狀態

步驟 3：從已完成的工作取得資訊

ISV 和通道合作夥伴應如何共同使用 API 進行多方私人供應專案

意見反應

其他資源

共用方式為

私人供應項目提交 API 概觀

詞彙

支援的案例

準備好使用此 API

步驟 1：完成使用Microsoft產品擷取 API 的必要條件（一次性）

步驟 2：取得Microsoft Entra 存取令牌（每次）

尋找產品、方案和私人供應項目標識碼

擷取

擷取特定產品的方案

擷取私人供應專案

如何使用 API

步驟 1：提出要求

步驟 2：輪詢作業狀態

步驟 3：從已完成的工作取得資訊

ISV 和通道合作夥伴應如何共同使用 API 進行多方私人供應專案

相關內容

意見反應

其他資源