商業市集的產品擷取 API

發行項
06/14/2024

產品擷取 API 是現代化 API，可統一所有商業市集產品的所有現有提交 API。 API 可讓您在合作夥伴中心帳戶內建立、發佈和管理與產品和方案相關聯的資源。它會使用宣告式模式來提交要求，其中會指出所需狀態，而不是指定個別步驟以達到所需狀態。

本文提供如何開始使用任何商業市集供應項目類型的API的指引。 SaaS、VM 、私人供應專案和容器供應專案類型目前支援產品擷取 API，且處於預覽狀態。如需供應項目專屬的指引，請檢閱每個供應項目類型的API指引。

重要

自 2023 年 6 月 30 日起，Azure Active Directory （Azure AD） Graph 已淘汰。接下來，我們不會對 Azure AD Graph 進行進一步的投資。 Azure AD Graph API 除了安全性相關修正之外，沒有 SLA 或維護承諾。我們只會對 Microsoft Graph 投資發展新的功能。

我們會以累加步驟淘汰 Azure AD Graph，讓您有足夠的時間將應用程式移轉至 Microsoft Graph API。在稍後宣佈的日期，我們將封鎖使用 Azure AD Graph 建立任何新的應用程式。

若要深入瞭解，請參閱重要事項：Azure AD Graph 淘汰和 Powershell 模組淘汰。

開始使用

您可以使用工作負載名稱 「product-ingestion」下的 MSGraph API 來存取產品擷取 API。基底 URL 為 https://graph.microsoft.com/rp/product-ingestion。

若要使用產品擷取 API，您必須先取得下列專案：

Microsoft Entra 識別符，並確定您具有目錄的全域管理員許可權
Microsoft Entra 應用程式
Microsoft Entra 存取令牌

步驟 1：完成必要條件

開始撰寫程式代碼以呼叫產品擷取 API 之前，請確定您已完成下列必要條件。

您（或貴組織）必須具有 Microsoft Entra 目錄，而且您必須具有目錄的全域管理員許可權。如果您已經從 Microsoft 使用 Microsoft 365 或其他商務服務，則您已經Microsoft Entra 目錄。否則，您可以免費在合作夥伴中心建立新的Microsoft Entra標識符。
您必須將Microsoft Entra 應用程式與您的合作夥伴中心帳戶產生關聯，並取得您的租用戶標識碼、用戶端標識碼和密鑰。您需要這些專案，才能取得您要在呼叫 Microsoft Store 提交 API 時使用的 Microsoft Entra 存取令牌。

將Microsoft Entra 應用程式與您的合作夥伴中心帳戶建立關聯

若要使用產品擷取 API，您必須將Microsoft Entra 應用程式與合作夥伴中心帳戶產生關聯、擷取應用程式的租用戶標識碼和用戶端識別碼，以及產生密鑰。 Microsoft Entra 應用程式代表您要從中呼叫產品擷取 API 的應用程式或服務。您需要租使用者標識碼、用戶端標識碼和密鑰，才能取得要傳遞至 API 的Microsoft Entra 存取令牌。

注意

您只需要執行此工作一次。擁有租使用者標識碼、用戶端標識碼和密鑰之後，您隨時都可以重複使用它們，以建立新的Microsoft Entra 存取令牌。

在合作夥伴中心中，將組織的合作夥伴中心帳戶與組織的 Microsoft Entra 目錄建立關聯。
從合作夥伴中心的 [帳戶設定] 區段中的 [使用者] 頁面，新增Microsoft Entra 應用程式，代表您將用來存取合作夥伴中心帳戶提交的應用程式或服務。請確定您將此應用程式指派給 管理員 角色。如果您的 Microsoft Entra 目錄中還沒有任何應用程式存在，請在合作夥伴中心建立新的 Microsoft Entra 應用程式。合作夥伴中心會為應用程式建立兩種類型的專案，一個作為服務主體，另一種則建立為Microsoft Entra 應用程式類型。
返回 [ 使用者] 頁面，選取您Microsoft Entra 應用程式的名稱以移至應用程式設定，然後複製 [租使用者標識符 ] 和 [用戶端標識符 ] 值。
選取 [ 新增金鑰]。在下列畫面上 ，複製 [金鑰 ] 值。離開此頁面之後，您將無法再次存取此資訊。如需詳細資訊，請參閱管理Microsoft Entra 應用程式的密鑰。

步驟 2：取得Microsoft Entra 存取令牌

若要呼叫產品擷取 API 中的任何方法，您必須先取得Microsoft Entra 存取令牌，以傳遞至 API 中每個方法的 Authorization 標頭。存取令牌會在發行后 60 分鐘到期。之後，您可以重新整理它，以便在未來呼叫 API 時使用它。

若要取得存取令牌，請遵循服務對服務呼叫中的指示，使用客戶端認證將傳送 HTTP POST 至 https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token 端點。以下是範例要求：

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded;

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&scope=https://graph.microsoft.com/.default

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

概念

開始之前，您必須瞭解一些基本概念。

資源

API 是以資源類型為結構，其中每個類型都是使用「$schema」屬性所參考的專用架構定義來描述。架構是由該資源的組態屬性所組成。資源是建立和更新指定產品各層面設定的基礎。如需資源類型及其架構的完整清單，請參閱資源 API 參考。

Durable ID

長期標識碼是系統產生的全域標識碼，用來唯一識別任何資源。每個資源都有相關聯的「ID」屬性，結合資源類型名稱時，構成資源的持久標識碼。參考資源以擷取或修改時，會使用永久性標識碼。

格式：

\<resource-type>/\<id>

範例：

            { 
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
                "id": "product/12345678-abcd-efgh-1234-12345678901", // durable ID
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo"
                },
                "type": "softwareAsAService", // Product types that can be specified include azureContainer, azureVirtualMachine, softwareAsAService
                "alias": "Contoso Image Resizing Service"
            }

外部 ID

外部標識碼是另一個可用來參考特定產品或方案的唯一標識碼。這是參考這些資源的替代方式，而不是使用耐久標識符。產品的外部標識符會轉譯為其「offerID」，而方案的外部標識符會轉譯為其「planID」，如在「身分識別」屬性下建立時所定義。

範例：

            { 
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
                "id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
                "identity": {
                  "externalID": "gold-annual"
                },
                "azureRegions": [
                    "azureGlobal"
                  ],
                "alias": "Gold - Annual payment",
                "product": "product/12345678-abcd-efgh-1234-12345678901",
            }

API 方法

有四個管理 API 可用來執行不同的動作，例如查詢現有資源、進行設定更新，以及檢查要求的狀態。

注意

所有要求都需要您設定您想要作為回應一部分的架構版本（$version 查詢參數）。

API 類型	說明	HTTP 方法和路徑
查詢	依下列方式擷取現有的資源： -方法 1：“resource-tree” 資源類型 -方法 2：durable-id -方法 3：查詢字串參數	-方法 1： `GET resource-tree/<product-durableID>` -方法 2： `GET <resource-durableID>` -Method 3： `GET <resourceType>?<query parameters>`
設定送出	提交建立或更新一或多個資源的要求。成功處理時，會傳回jobID，可用來擷取要求的狀態。此 API 類型可用來更新草稿狀態和發佈變更、同步處理私人物件，以及修改資源生命周期狀態。	`POST configure`
設定狀態	透過jobID擷取擱置要求的狀態。	`GET configure/<jobID>/status`
設定狀態詳細數據	透過jobID擷取已完成要求的詳細摘要，包括更新的資源。	`GET configure/<jobID>`
取消設定	取消指定的設定作業。	`POST configure/<jobID>/cancel`

一般工作流程

若要更新現有的資源，一般工作流程會是：

擷取現有的資源組態（API 類型： 透過資源樹狀結構查詢）*
進行任何必要的更新，然後提交設定要求（API 類型：設定提交）
檢查要求的狀態（API 類型：設定狀態和設定狀態詳細數據）

* 建立新資源時可以套用這個相同的工作流程，但不要擷取資源（步驟 1），請使用 Resource API 參考數據表，以確保您使用您正在建立之資源類型的目前架構。

總而言之，不論您要建立新的或修改現有資源，此影像都會顯示用來提交組態要求的一般呼叫模式。

螢幕快照，說明用來提交設定要求的一般呼叫模式。

注意

請參閱每個供應項目類型一節的 API 指引，請務必檢閱您所管理 之供應項目類型 特有的任何其他必要條件。

擷取現有的資源組態

更新現有資源之前，請務必先擷取它們，以確保您有最新的設定。有數種方式可透過 GET 呼叫擷取資源。請參閱下面詳述的方法 1，以擷取單一 API 呼叫中特定產品內的所有資源。

方法 1：資源樹狀結構

Schema: https://``schema.mp.microsoft.com``/schema/resource-tree/2022-03-01-preview2

GET resource-tree/<product-durableID>?$version=<schema-version>

您可以使用「資源樹狀結構」資源類型，以及產品的耐久標識符，擷取特定產品內的所有資源組態。

每個資源可用的最新架構版本可能不同。執行資源樹狀結構要求時，指定的架構版本會指定產品中每個資源的傳回版本。指定的版本會做為「最大」版本限制，因為它會傳回所有相同或較低版本資源可用的最新架構版本。例如，如果可用的最新方案清單版本是 “2022-03-01-preview3”，則如果您要在資源樹狀目錄 GET 要求中指定 “2022-03-01-preview5”，回應將會呈現此版本。不過，如果要求「2022-03-01-preview2」作為資源樹狀結構版本，這會傳回「2022-03-01-preview2」方案清單資源，即使可用的最新版本是 “2022-03-01-preview3”。建議您使用每個資源的最新可用版本，以確保您使用更新的架構搭配新支援的功能。

注意

如果您不知道產品的耐久標識符，您可以使用產品的外部標識符來執行來擷取產品資源 GET product?externalID=<product-externalID>&$version=<product-schema-version>。此要求會利用下列方法 3 中詳述的查詢字串參數。回應會包含產品的耐久標識符，您可以用於未來的要求。

根據預設，當您使用「resource-tree」執行 GET 呼叫時，您會取回資源的草稿版本。不過，藉由傳遞「targetType」查詢參數，您可以指定所需的目標來擷取「preview」或「live」資料。在下列範例中，GET 呼叫會傳回產品「12345678-abcd-efgh-1234-12345678901」下所有資源的預覽環境設定。

範例 GET 呼叫：

GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?targetType="preview"&$version=2022-03-01-preview5

範例回應：

        {
          "$schema": "https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2",
          "root": "product/12345678-abcd-efgh-1234-12345678901",
          "target": {
            "targetType": "preview"
          },
          "resources": [
          { 
            "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
            "id": "product/12345678-abcd-efgh-1234-12345678901",
            "identity": {
              "externalID": "ds-contoso-image-resize-demo"
            },
            "type": "softwareAsAService",
            "alias": "Contoso Image Resizing Service"
          },
          { 
            "$schema": "https://schema.mp.microsoft.com/schema/property/2022-03-01-preview3",
            "id": "property/12345678-abcd-efgh-1234-12345678901/public/main",
            "product": "product/12345678-abcd-efgh-1234-12345678901",
            "kind": "azureSaaS",
            "termsConditions": "false",
            "categories": {
          "developer-tools-saas": [
            "devService"
          ]
            }
          },
          {
            "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
            "id": "plan/12345678-abcd-efgh-1234-12345678901/4e0bfefa-b993-4b79-a426-871c3bf236a5",
            "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
          ...
          }, 
              // The response would include all existing resources within this product.
          {
              ...
          }]
        }

方法 2：Durable ID

GET <resource-durableID>?$version=<schema-version>

使用其持久標識符擷取特定資源。建立資源之後，永久性標識符一律會維持不變，並可用來藉由呼叫 GET 方法擷取該資源的最新草稿變更。例如，下列要求會使用「2022-03-01-preview3」架構版本傳回此特定產品的草稿組態。

GET product/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview3

重要

這個方法僅用於擷取草稿組態。如果您想要擷取預覽或實時數據，請使用「資源樹狀結構」方法，如上所述。

若要尋找資源的持久識別碼，您可以：

使用「resource-tree」方法來擷取產品內的所有資源，以及其各自的耐久標識符，或
擷取已完成資源組態要求的詳細數據，其中包含在要求中建立或更新之所有資源的持久標識符。

請記住，“ID” 屬性是個別資源的 durable-id。

方法 3：查詢字串參數

GET <resourceType>?<query parameters>&$version=<schema-version>

這個方法可用來查詢與特定帳戶相關聯的特定資源類型。例如，您可以使用單一 GET 呼叫來擷取特定產品類型的所有產品。查詢字串參數可用來查詢與產品、方案或提交相關的詳細數據。

下表顯示每個支援之資源類型的支持查詢參數。並非所有資源類型都支援每個查詢參數。如需目前支持的查詢字串完整清單，請參閱此資料表。

資源類型	參數	查詢字串範例
計劃	產品`` ExternalId $maxpagesize continuationToken$version``	`GET plan?product=<product-durableID>&$version=<schema-version>` `GET plan?product=<product-durableID>&externalID=<plan-externalID>&$version=<schema-version>` `GET plan?product=<product-durableID>&$maxpagesize=<#>&$version=<schema-version>` `GET plan?product=<product-durableID>&continuationToken=<token>&$version=<schema-version>`
product	ExternalId type $maxpagesize continuationToken$version`*`	`GET product?externalID=<product-externalID>&$version=<schema-version>` `GET product?type=<product-type>&$version=<schema-version>` `GET product?$maxpagesize=<#>&$version=<schema-version>` `GET product?continuationToken=<token>&$version=<schema-version>`
submission	targetType $maxpagesize continuationToken$version`*`	`GET submission/<product-durableID>?targetType=<environment>&$version=<schema-version>` `GET submission/<product-id>?$maxpagesize=<#>&continuationToken=<token>&$version=<schema-version>`
resource-tree	targetType$version`*`	`GET resource-tree/<product-durableID>?targetType=<environment>&$version=<schema-version>`

* 一律需要產品和$version參數。

每個支援查詢參數的功能：

product – 在 “plan” 資源類型的內容中傳遞 “product” 參數時，它會傳回該特定產品內的所有方案。
externalID – 在產品或方案的內容中傳遞「externalID」參數時，它會傳回該個別產品或方案的組態。不同於 “resource-tree” 方法，此查詢字串參數只會傳回該資源的詳細數據，而不是其中的所有資源。
type – 在 “product” 資源類型的內容中傳遞 “type” 參數時，它會傳回與您的帳戶相關聯的所有類型產品。例如，藉由指定「type=softwareAsAService」，將會傳回您所有的 SaaS 產品。
targetType – 這會傳回所使用資源類型內容中特定環境的數據。支援的「targetType」值為「draft」、“preview” 或 “live”。
$maxpagesize – 藉由指定最大頁面大小，以正整數的形式，此參數可用來限制查詢先前提交時搜尋的結果。
continuationToken – 此參數可以搭配 “$maxpagesize”參數使用，以查詢搜尋中可用的另一組結果。 “continuationToken” 值是在上一頁的回應中提供。
$version – 這是所有呼叫的必要參數，它會指定您想要針對所提出要求之回應的架構版本。每個資源可用的最新架構版本可能不同，而指定的版本會做為「最大」版本限制。如果有的話，系統會傳回確切的架構版本，或比要求的版本還舊的最接近版本。即使有較新的架構變更，這也有助於維護程式碼的運作，但為了利用最新的功能，建議您使用每個架構的最新可用版本。

查詢您的提交

您可以藉由執行來 GET submission/<product-durableID>擷取現有的產品提交。根據預設，您會取回所有使用中提交，包括草稿參考，但您也可以使用「targetType」查詢參數來額外查詢特定環境：（GET submission/<product-durableID>?targetType=<environment>&$version=<version>）。

重要

一旦「預覽」提交推送至「即時」，就會取代任何先前的「即時」提交。發生這種情況時，數據現在同時代表「預覽」和「即時」環境，直到新的提交發佈至「預覽」為止。

範例要求：

GET https://graph.microsoft.com/rp/product-ingestion/submission/12345678-abcd-efgh-1234-12345678901?$version=2022-03-01-preview2

範例回應：

此範例顯示與產品標識碼 「12345678-abcd-efgh-1234-12345678901」相關聯的使用中提交 GET 要求。作用中的「即時」提交（提交/12345678-abcd-efgh-1234-12345678901/1152921515689847470）已發行至預覽版，然後稍後再上線。當此提交推送至 2022 年 1 月 25 日上線時，它代表預覽版和即時提交，直到新的預覽提交（提交/12345678-abcd-efgh-12345678901/1152921515689848683）於 2022 年 2 月 4 日建立。

            {
              "value": [
                {
                  "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                  "id": "submission/12345678-abcd-efgh-1234-12345688901/0",
                  "product": "product/12345678-abcd-efgh-1234-12345678901",
                  "target": {
                    "targetType": "draft"
                  }
                },
                {
                  "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                  "id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689847470",
                  "product": "product/12345678-abcd-efgh-1234-12345678901",
                  "target": {
                    "targetType": "live"
                  },
                  "status": "completed",
                  "result": "succeeded",
                  "created": "2022-01-25T07:13:06.4408032Z"
                },
                {
                  "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                  "id": "submission/12345678-abcd-efgh-1234-12345678901/1152921515689848683",
                  "product": "product/12345678-abcd-efgh-1234-12345678901",
                  "target": {
                    "targetType": "preview"
                  },
                  "status": "completed",
                  "result": "succeeded",
                  "created": "2022-02-04T20:07:22.4220588Z"
                }
              ]
            }

建立新產品和資源

您可以在單一組態要求中建立新的資源，包括新產品。藉由使用資源 API 參考數據表，您可以擷取您想要建立之資源類型的架構。這可確保您使用最新的架構，因此設定所有必要的屬性來建立資源。

如果您要建立新產品，需求會因產品類型而異。因此，您必須提供不同的資源。您可以參考個別產品類型的對應商業市集檔，以確保您在要求中設定基本需求。或者，您可以只使用產品資源提出設定要求。建立產品之後，請呼叫設定狀態詳細數據 API 來擷取已建立的產品資源，並尋找其持久標識符來呼叫資源樹狀查詢 API。回應會針對您所建立的產品類型傳回適用的支持資源。

同樣地，若要在現有產品內建立新的資源，您也需要擷取該特定資源類型的最新架構。檢閱資源相依性，確定您提供相依資源作為組態要求的一部分。

使用架構建構資源之後，請瞭解如何提出組態要求。

修改現有的產品和資源

您可以使用設定承載來提交更新。此承載包含一或多個資源類型，而「$schema」屬性表示所參考的資源類型。

提示

建議您先擷取現有的資源，再發佈更新，以確保您正在利用最新的設定。

修改資源之後，請瞭解如何提出設定要求。

組態要求

您可以在相同的承載中編輯和發佈。若要提交設定要求，請使用設定 API 的 HTTP POST 方法。設定承載是由指出所需變更的資源數位所組成。所有編輯只會影響草稿版本，直到您明確提交提交資源以發佈草稿變更為止。發佈至預覽或即時時，請包含提交資源並指定目標環境。提交要求之前，您必須知道如何參考資源並瞭解其相依性。

Schema:<https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2>

提交組態要求后，您可以使用jobID來取得 configure-status 物件，讓您可用來追蹤要求的進度和結果。

Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>

資源參考和相依性

參考資料

若要參考設定要求中的現有資源，請提供資源的「$schema」類型以及資源的持久標識符。在產品和方案的情況下，您也可以透過其外部標識元參考這些資源。

持久性識別碼可以在「ID」屬性中找到，例如，如果這是我們想要在另一個資源中參考的產品資源：

            { 
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
                "id": "product/12345678-abcd-efgh-1234-12345678901",
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo"
                },
                "type": "softwareAsAService",
                "alias": "Contoso Image Resizing Service"
            }

持久性標識符會是「product/071b135e-9faf-4ff7-b113-a3f25bb0f468」。。

接著，您可以在下列清單資源範例中使用持久性標識符，方法是將它設定為 “product” 資源架構屬性，如下所示：

            {
                "$schema": "https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5", 
                "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468", // product durable ID
                  ...
              }

產品與計劃資源的外部標識碼定義於「身分識別」屬性內。

            {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2", 
                "alias": "Gold - Annual payment",
                "identity": {"externalID": "gold-annual"},
                "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468",
                  ...
              }

然後，計劃外部標識碼「gold-annual」可由其他後續資源參考，格式如下：

              {
                "$schema": "https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5", 
                "product": "product/071b135e-9faf-4ff7-b113-a3f25bb0f468"}
                "plan": {"externalID": "gold-annual"}
                  ...
              }

範例要求：

在此範例中，會使用設定承載來建立新的 SaaS 產品，其外部標識碼為 “ds-contoso-image-resize-demo”。建立此產品之後，您稍後可以使用其耐久標識碼或外部標識碼來參考本產品。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
                { 
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3",
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo"
                },
                "type": "softwareAsAService",
                "alias": " Contoso Image Resizing Service"
              }
              ]
            }

範例回應：

            {
  "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
  "jobID": "071b135e-9faf-4ff7-b113-a3f25bb0f468",
  "jobStatus": "running",
  "jobResult": "pending",
  "jobStart": "2022-08-18T16:35:56.5917185Z",
  "jobEnd": "0001-01-01T00:00:00",
  "errors": []
}

然後，您可以透過設定狀態 API 使用 jobID 來檢查要求的狀態。

相依性

某些資源相依於建立另一個資源作為必要條件。在此情況下，我們會在相同的承載中使用「resourceName」屬性來表示計劃資源中產品資源的相依性，因為我們在相同的要求中建立兩者。

“resourceName” 只會用來識別每個資源，作為您正在執行之設定要求的一部分。此值不會是資源數據的一部分，也不會儲存，也不會公開給客戶。此外，如果設定要求中有任何錯誤，“resourceName” 將用來呼叫錯誤所屬的資源。

範例要求：

在此範例中，產品必須在計劃之前建立，因此會使用「resourceName」屬性。正在建立的產品「myNewProduct」會是用於「resourceName」的值，並在相依計劃資源內參考。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
              {
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3", 
                "resourceName": "myNewProduct", 
                "alias": "Contoso Image Resizing Service",
                ...
              }, 
              {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2", 
                "alias": " Gold - Annual payment",
                "product": {"resourceName": "myNewProduct"}
                  ...
              }, 
              }]
            }

提交資源

如果發佈至「預覽」或「即時」，請在您的要求中包含提交資源，其中包含：

“product” 屬性，表示其耐久標識符或外部標識符所參考的產品更新
“targetType” 屬性，表示目標環境

特別發佈至即時時，您要發佈的預覽提交「標識碼」：

              {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",    
                "product": "product/12345678-abcd-efgh-1234-12345678901", 
                "target": { "targetType": "live" }
              }

注意

如果您沒有包含提交資源，則只會對草稿狀態進行變更。

發佈至預覽

商業產品類型支援預覽環境，而且每個更新必須先發佈至預覽，才能上線。您無法直接發佈至即時。

重要

例外狀況是變更您方案的私用物件時。特別將更新同步處理至私人物件時，這些變更會同時傳播到預覽和即時。

有兩種方式可將資源發佈至預覽環境。如果需要對預覽提交進行任何變更，請執行另一個 GET 要求、進行必要的變更，然後再次推送變更。您不需要先進行初始變更。

方法 1：發佈所有草稿資源

如果您想要發佈您所做的每個草稿變更，您可以使用提交資源傳送設定要求，以將預覽環境設定為「targetType」。如下列範例所示，您不需要明確提供需要更新的每個資源，因為此方法會將所有變更發佈至目標環境，在此案例中為預覽。您只需要提供設定 API 端點和提交資源。

範例要求：

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
              {
            // Below is the submission resource to publish to preview
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
                "target": { "targetType": "preview" }
              }
              ]
            }

方法 2：發佈特定草稿資源（也稱為模組化發佈）

或者，如果您尚未準備好跨各種資源發佈所有草稿變更，只要提供您想要發佈的資源以及提交資源來觸發模組化發佈。您也可以使用此方法來變更資源，並同時發佈資源，而不是做為大量更新的一部分，如同透過方法 1 完成。針對模組化發佈，除了產品層級詳細數據（例如清單、可用性、套件、轉銷商）以外，所有資源都必須適用於您的產品類型。

範例要求：

在此範例中，產品中的資源會明確提供為模組化發行的一部分，後面接著提交資源。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
              {
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2", 
                "id": "product/12345678-abcd-efgh-1234-12345678901",
                ...
              },
              {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2", 
                  ...
              }, 
              // additional resources
              {
                  ...
              },
              // Below is the submission resource to publish to preview
              {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
                "target": { "targetType": "preview" }
              }
              ]
            }

發佈至即時

測試並驗證預覽版中的變更之後，您可以傳送具有預覽提交「標識碼」的設定要求，並將「targetType」設定為 [即時] 來推送變更。若要尋找預覽提交的「標識碼」，以納入您的設定要求，請參閱查詢您的提交。

重要

不同於發佈至預覽版時，沒有選項可在發佈至即時時執行模組化發佈。因此，請務必確定您已在進行變更之前先驗證預覽提交。

範例要求：

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
              // Below is the submission resource, including the preview submission id, to publish to live.
              {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2",
                "id": "submission/12345678-abcd-efgh-1234-12345678901/11521167929065",    
                "product": "product/12345678-abcd-efgh-1234-12345678901", // This is the product durable ID
                "target": { "targetType": "live" }
              }
              ]
            }

檢查要求的狀態

無論您的設定要求或所做的變更中包含的資源為何，在成功處理要求之後不久，您就會在回應中取得 configure-status 物件。 “jobID” 很重要，因為稍後可用來檢查要求的狀態。

Schema: <https://``schema.mp.microsoft.com``/schema/configure-status/2022-03-01-preview2>

提交要求的範例回應：

            {
                "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
                "jobID": "d4261631-c583-4949-a612-5150882632e9",
                "jobStatus": "notStarted",
                "jobResult": "pending",
                "jobStart": "2022-03-01T13:32:43.123456Z",
                "jobEnd": "0001-01-01T00:00:00",
                "errors": []
            }

擱置要求的狀態

您可以擷取狀態，直到作業使用下列呼叫完成，並輸入要求的「jobID」。如果您的要求發生任何問題，物件也可能包含錯誤清單。

GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>/status?$version=2022-03-01-preview2

請記住，完成的時間可能會因要求的複雜度而有所不同，

已完成要求的摘要

一旦設定要求作業完成，成功或失敗，您就可以使用「jobID」取得建立或更新的資源清單。

注意

如果您在作業完成之前進行此呼叫，它將會失敗。此外，它只會傳回已成功完成的資源，或在取消前只傳回已完成的資源。

Schema: <https://``schema.mp.microsoft.com``/schema/configure-detail/2022-03-01-preview2>

GET https://graph.microsoft.com/rp/product-ingestion/configure/<jobID>?$version=2022-03-01-preview2

範例要求：

在下列範例中，GET 要求可用來擷取先前範例中建立新 SaaS 產品的設定要求摘要詳細數據。回應是 configure-detail 物件，其中包含已建立的產品資源及其持久標識符的資源數位。

GET https://graph.microsoft.com/rp/product-ingestion/configure/071b135e-9faf-4ff7-b113-a3f25bb0f468?$version=2022-03-01-preview2

範例回應：

            {
"$schema": "https://schema.mp.microsoft.com/schema/configure-detail/2022-03-01-preview2",
"resources": [
{ 
                "$schema": "https://schema.mp.microsoft.com/schema/product/2022-03-01-preview2",
                "id": "product/12345678-abcd-efgh-1234-12345678901",
                "identity": {
                  "externalID": "ds-contoso-image-resize-demo "
                },
                "type": "softwareAsAService",
                "alias": "Contoso Image Resizing Service"
              }
]
}

取消設定要求

作業完成之前，您可以視需要嘗試取消作業。對於長時間執行的要求，例如發佈至「預覽」或「即時」，如果作業已足夠完整處理，則取消要求可能會遭到拒絕。

若要取消作業，請對取消端點進行POST呼叫，並提供您想要取消之要求的作業標識碼。

POST https://graph.microsoft.com/rp/product-ingestion/configure<jobID>/cancel?$version=2022-03-01-preview2

範例要求：

POST <https://graph.microsoft.com/rp/product-ingestion/configure/d4261631-c583-4949-a612-5150882632e9/cancel?$version=2022-03-01-preview2>

成功取消要求的範例回應：

            {
                "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
                "jobID": "d4261631-c583-4949-a612-5150882632e9",
                "jobStatus": "completed",
                "jobResult": "cancelled",
                "jobStart": "2022-03-01-T13:32:43.123456Z",
                "jobEnd": "2022-03-01T17:34:21.5225132Z",
                "errors": []
            }

不允許取消時範例回應： HTTP Status code: 400

內容：

            {
              "error": {
                "code": "badRequest",
                "message": "Cannot cancel job, job has already completed.",
                "details": []
              }
}

重要

請記住，取消僅適用於尚未處理的資源。有些資源可能已經完成處理，而且會反映最新的組態更新，儘管取消要求。

您可以在取消之後擷取設定要求的摘要，以確認在取消之前已處理哪些資源（如果有的話）。

同步處理私人適用對象

針對實時產品，可以同時執行草稿、預覽和實時環境的私用物件更新，而不需要發佈。您可以使用「price-and-availability-update-private-audiences」資源同步處理私人物件，方法是指定要從特定方案中新增或移除哪些物件。這會同步草稿、預覽和實時環境，以擁有相同的私人物件值。同步處理私人物件時，您不需要提供提交資源。

若要編輯草稿物件，請使用“price-and-availability-plan” 資源和 “privateAudiences” 屬性。這需要經過一般發佈流程，才能在預覽和實時中設定值。

重要

支援的物件類型為「訂用帳戶」、「ea」、「msdn」和「租使用者」，但支援這些類型會因產品類型而異。如果您的產品支援多個識別碼類型來設定私人物件（例如，租使用者標識碼和訂用帳戶標識碼），則第一次提供新的標識符類型時，您必須執行完整發佈。在此情況下，您無法同步處理私人物件。

同步私人物件設定的範例要求：

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

        {
          "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
          "resources": [
          {
            "$schema": "https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview2",
            "product": "product/12345678-abcd-efgh-1234-12345678901", // product durable ID
            "plan": "plan/12345678-abcd-efgh-1234-12345678901/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b", //plan durable ID 
            "privateAudiences":
            {
              "add ":
              [
                  {
            "type": "tenant",
                    "id": "4c2bdcdc-f10e-468d-8a2a-0832e089215b",
                    "label": "test 1"
                  }
              ],
              "remove ":
              [
                {
            "type": "subscription",
                    "id": "412c45bf-c99a-4e96-b683-77b0aa2dd09e",
                    "label": "test 2"
                }
              ]
            }
          }
          ]
        }

設定潛在客戶管理

將客戶關係管理（CRM）系統與您的商業市集產品連線，以便在客戶表達興趣或部署產品時收到客戶連絡資訊。您可以在產品建立期間或之後隨時修改此連線。若要深入瞭解，請參閱取得潛在客戶。

設定潛在客戶管理的範例要求：

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

        {
          "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
          "resources": [
            {
            "$schema": "https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3",
            "id": "customer-leads/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
            "product": "product/a0c6484f-b4fb-4129-ac6b-35f2b5628089",
            "leadDestination": "httpsEndpoint",
            "httpsEndpointLeadConfiguration": {
              "httpsEndpointUrl": "https://www.your-crm.com/triggers/invoke"
            }
          }  
          ]
        }

資源生命周期狀態

您可以採取不同的動作來對應至資源的生命周期狀態。並非所有資源都有生命週期狀態，並非所有資源都支援所有生命周期狀態。若要探索資源是否有生命周期狀態和支援哪些值，您可以檢查資源架構中是否有屬性 “lifecycleState”。以下詳述各種支援的生命周期狀態。

已刪除

您可以將「lifecycleState」屬性更新為「deleted」來刪除特定資源。您只能刪除之前尚未發布的草稿資源。此動作無法復原。

範例要求：

在下列範例中，會刪除「基本」草稿計劃。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

        {
          "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
          "resources": [
            {
            "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
            "id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
            "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
            "identity": { "externalID": "basic" },
            "alias": "basic plan"
            "lifecycleState": "deleted"
            }
          ]
        }

已取代

淘汰會從商業市集移除資源。若要取代，請在支援它的資源上，將 “lifecycleState” 屬性設定為 “deprecated”。有各種層級的淘汰。所有產品類型都支援取代整個產品和個別方案。若要稍後還原已被取代的資源，請參閱「一般Available」生命周期狀態。

產品淘汰的範例要求：

在下列範例中，產品的即時提交設定為取代。套用此變更之後，系統會自動發佈至即時生效。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
                {
                "$schema": "https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2 ",
                "id": "submission/9f8af57f-ab07-461b-8404-50e10e5e80fb/1152921515689848683",
                "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
                "target": {
                    "targetType": "live"
                  },
                "lifecycleState": "deprecated"
                }
              ]
            }

當取代計劃時， 「lifecycleState」 屬性必須變更為「已淘汰」，然後必須將變更發佈至「預覽」，然後「即時」讓取代生效。這與產品層級淘汰不同，在實時環境中會自動設定淘汰。

計劃淘汰的範例要求：

在下列範例中，SaaS 產品內的方案會設定為取代。請記住，若要套用這項變更，您稍後可以使用提交資源發佈。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
                {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2 ",
                "id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
                "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
                "identity": { "externalID": "basic" },
                "alias": "basic plan"
                "lifecycleState": "deprecated"
                }
              ]
            }

根據產品類型，還有其他形式的取代會有所不同。深入瞭解 SaaS、虛擬機和容器的淘汰。

正式推出

generallyAvailable 是所有資源的預設生命周期狀態。資源已被取代之後，您可以將 “lifecycleState” 屬性變更回 “generallyAvailable”。若要還原已淘汰的產品，您必須發佈產品，才能即時預覽。您可以在其各自的文章中找到 SaaS、VM 和容器的範例。

計劃還原的範例要求：

在下列範例中，計劃是要還原的。若要套用這項變更，您稍後必須一路發佈，才能使用提交資源。

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2022-03-01-preview2

            {
              "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2"
              "resources": [
                {
                "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2",
                "id": "plan/9f8af57f-ab07-461b-8404-50e10e5e80fb/7e70b11f-809e-4c45-ae2f-1fb3ceaca33b",
                "product": "product/9f8af57f-ab07-461b-8404-50e10e5e80fb",
                "identity": { "externalID": "basic" },
                "alias": "basic plan"
                "lifecycleState": "generallyAvailable"
                }
              ]
            }

資源 API 參考

下列架構版本僅適用於預覽，一旦 API 正式推出，將會變更。

注意

您可以在這裏檢視現有的可用資源及其版本： resources-index

資源類型	說明	結構描述
commercial-marketplace-setup	描述商業市集中產品的可交易設定。	https://schema.mp.microsoft.com/schema/commercial-marketplace-setup/2022-03-01-preview2
潛在客戶	允許連線到 CRM 系統以接收潛在客戶。	https://schema.mp.microsoft.com/schema/customer-leads/2022-03-01-preview3
清單	這包括產品的描述，其會顯示在商業市集店面Microsoft。	https://schema.mp.microsoft.com/schema/listing/2022-03-01-preview5
listing-asset	連結到清單資源的螢幕快照和營銷資產。	https://schema.mp.microsoft.com/schema/listing-asset/2022-03-01-preview5
listing-trailer	連結至清單資源的影片資產。	https://schema.mp.microsoft.com/schema/listing-trailer/2022-03-01-preview5
microsoft365-integration	Microsoft 365 啟用和類型選取。	https://schema.mp.microsoft.com/schema/microsoft365-integration/2022-03-01-preview2
計劃	若要建立計劃，然後由您設定的計劃層級資源參考，例如計劃清單。	https://schema.mp.microsoft.com/schema/plan/2022-03-01-preview2
plan-listing	定義方案名稱和描述，因為您希望它們出現在商業市集中。	https://schema.mp.microsoft.com/schema/plan-listing/2022-03-01-preview5
price-and-availability-custom-meter	定義跨方案共用的自定義計量。	https://schema.mp.microsoft.com/schema/price-and-availability-custom-meter/2022-03-01-preview3
price-and-availability-offer	定義有限的物件，您可以在發佈產品之前先檢閱您的產品。	https://schema.mp.microsoft.com/schema/price-and-availability-offer/2022-03-01-preview3
price-and-availability-plan	設定此方案可供使用的市場、所需的獲利模型、價格和計費條款。	https://schema.mp.microsoft.com/schema/price-and-availability-plan/2022-03-01-preview4
price-and-availability-update-private-audiences	您可以在草稿、預覽和即時環境中同時執行私人物件更新，而不需要發佈。	https://schema.mp.microsoft.com/schema/price-and-availability-update-private-audiences/2022-03-01-preview3
private-and-availability-private-offer-plan	用來設定私人供應專案內使用之產品/方案定價的絕對定價詳細數據	https://schema.mp.microsoft.com/schema/price-and-availability-private-offer-plan/2022-07-01
private-offer	定義私人供應專案的名稱和類型，其中包含供應專案條款和詳細數據，以及包含的產品/方案及其定價	https://schema.mp.microsoft.com/schema/private-offer/2022-07-01
product	這是主要資源，定義產品的名稱和類型，所有資源都會參考此專案。	https://schema.mp.microsoft.com/schema/product/2022-03-01-preview3
property	定義適用於您供應專案、您的應用程式版本和法律合約的類別和產業。	https://schema.mp.microsoft.com/schema/property/2022-03-01-preview5
轉銷商	在您想要讓產品可供使用雲端解決方案提供者（CSP）計劃中設定合作夥伴。	https://schema.mp.microsoft.com/schema/reseller/2022-03-01-preview2
resource-tree	描述該產品在指定之目標環境目前狀態的資源清單。	https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2
software-as-a-service-technical-configuration	可協助Microsoft商業市集連線到解決方案的技術詳細數據。	https://schema.mp.microsoft.com/schema/software-as-a-service-technical-configuration/2022-03-01-preview3
submission	可用來觸發產品上的不同動作，並指出產品無動於衷環境的發佈狀態（草稿、預覽和即時）。	https://schema.mp.microsoft.com/schema/submission/2022-03-01-preview2
virtual-machine-plan-technical-configuration	描述虛擬機和映像位置的技術詳細數據。	https://schema.mp.microsoft.com/schema/virtual-machine-plan-technical-configuration/2022-03-01-preview3
container-plan-technical-configuration	描述容器映像屬性的技術詳細數據。	https://schema.mp.microsoft.com/schema/container-plan-technical-configuration/2022-03-01-preview3

每個產品類型的 API 指引

產品擷取 API 未來將提供給其他產品類型。支援更多產品類型時，將會提供每個產品類型專屬的更多指引。

產品類型	產品類型特定資源
私人供應項目	透過產品擷取 API 建立和管理私人供應專案
SaaS	透過產品擷取 API 建立和管理 SaaS 供應專案
虛擬機器	透過產品擷取 API 建立和管理虛擬機供應專案
容器	透過產品擷取 API 建立和管理容器供應專案

API 版本和更新

更新	哪些變更了？
11-2023	所有架構端點已從 product-ingestion.azureedge.net 更新為 schema.mp.microsoft.com
12-2022	針對潛在客戶使用計算機擷取 API 的新架構版本 2022-03-01-preview3 現在可接受 clientID 和 clientSecret，同時設定潛在客戶並停止擷取 serverID 和連絡電子郵件字段。切換至新版本並提供 clientID 和 clientSecret，以繼續設定 Marketplace 供應專案的 Marketo 連接器。新的架構 URL： https://``schema.mp.microsoft.com``/schema/customer-leads/2022-03-01-preview3
09-2022	容器預覽支援已發行為 2022-03-01-preview4 版
08-2022	軟體即服務預覽支援已發行為版本 2022-03-01-preview3
08-2022	私人供應項目公開版本為 2022-07-01 版
05-2022	虛擬機預覽支援已發行為 2022-03-01-preview2 版

共用方式為

商業市集的產品擷取 API

開始使用

步驟 1：完成必要條件

將Microsoft Entra 應用程式與您的合作夥伴中心帳戶建立關聯

步驟 2：取得Microsoft Entra 存取令牌

概念

資源

Durable ID

外部 ID

API 方法

一般工作流程

擷取現有的資源組態

方法 1：資源樹狀結構

方法 2：Durable ID

方法 3：查詢字串參數

查詢您的提交

建立新產品和資源

修改現有的產品和資源

組態要求

資源參考和相依性

參考資料

相依性

提交資源

發佈至預覽

方法 1：發佈所有草稿資源

方法 2：發佈特定草稿資源（也稱為模組化發佈）

發佈至即時

檢查要求的狀態

擱置要求的狀態

已完成要求的摘要

取消設定要求

同步處理私人適用對象

設定潛在客戶管理

資源生命周期狀態

已刪除

已取代

正式推出

資源 API 參考

每個產品類型的 API 指引

API 版本和更新

相關內容

意見反應

其他資源