用于商业市场的产品引入 API

项目
01/29/2025

产品引入 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 ID，并确保你具有目录的全局管理员权限
Microsoft Entra 应用程序
Microsoft Entra 访问令牌

步骤 1：完成先决条件

开始编写代码以调用产品引入 API 之前，请确保已完成以下先决条件。

（或组织）必须具有Microsoft Entra 目录，并且必须具有目录的全局管理员权限。如果已从 Microsoft 使用 Microsoft 365 或其他业务服务，则已有 Microsoft Entra 目录。否则，可以在合作伙伴中心免费创建新的 Microsoft Entra ID。
必须将 Microsoft Entra 应用程序与合作伙伴中心帐户相关联，并获取租户 ID、客户端 ID 和密钥。需要这些来获取在调用 Microsoft 应用商店提交 API 时使用的 Microsoft Entra 访问令牌。

将 Microsoft Entra 应用程序与合作伙伴中心帐户相关联

若要使用产品引入 API，必须将Microsoft Entra 应用程序与合作伙伴中心帐户相关联，检索应用程序的租户 ID 和客户端 ID，并生成密钥。 Microsoft Entra 应用程序表示要从中调用产品引入 API 的应用或服务。需要租户 ID、客户端 ID 和密钥才能获取Microsoft Entra 访问令牌以传递给 API。

注意

此任务只需执行一次。拥有租户 ID、客户端 ID 和密钥后，随时可以重复使用它们以创建新的 Microsoft Entra 访问令牌。

在合作伙伴中心，将组织的合作伙伴中心帐户与组织的Microsoft Entra 目录相关联。
在合作伙伴中心“帐户设置”部分中的“用户”页面，添加表示用于访问合作伙伴中心帐户提交的应用或服务的 Microsoft Entra 应用程序。确保为此应用程序分配“管理者”角色。如果Microsoft Entra 目录中尚不存在该应用程序，请在合作伙伴中心创建新的 Microsoft Entra 应用程序。合作伙伴中心为应用程序创建两种类型的条目，一种为服务主体，另一种为 Microsoft Entra 应用程序类型。
返回到 “用户 ”页，选择Microsoft Entra 应用程序的名称以转到应用程序设置，并复制 租户 ID 和 客户端 ID 值。
选择“添加新密钥”。在下一个屏幕上，复制“密钥”值。离开此页后，不再可以访问此信息。有关详细信息，请参阅管理Microsoft Entra 应用程序的密钥。

步骤 2：获取Microsoft Entra 访问令牌

若要调用产品引入 API 中的任何方法，必须先获取一个Microsoft Entra 访问令牌，以传递给 API 中每个方法的授权 标头。访问令牌在颁发后 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 和 client_id 及 client_secret 参数中的 tenant_id 值中，请指定您在上一部分从合作伙伴中心检索到的应用程序的租户 ID、客户端 ID 和密钥。必须指定 scope 参数的 https://graph.microsoft.com/.default。

概念

在开始之前，需要了解一些基本概念。

资源

API 围绕资源类型进行结构化，其中每个类型都使用“$schema”属性引用的专用架构定义进行描述。架构由该资源的配置属性组成。资源是创建和更新给定产品各个方面配置的基础。有关资源类型及其架构的完整列表，请参阅资源 API 参考。

持久 ID

持久 ID 是系统生成的全局标识符，用于唯一标识任何资源。每个资源都有一个关联的“ID”属性，该属性与资源类型名称结合使用时，构成资源的持久 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

“外部 ID”是另一个唯一标识符，可用于引用特定产品或计划。这是不使用持久 ID 引用这些资源的替代方法。产品的外部 ID 转换为其“offerID”，计划的外部 ID 转换为其“planID”，如创建时“identity”属性下的定义。

示例：

            { 
                "$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：持久性 ID -方法 3：查询字符串参数	-方法 1： `GET resource-tree/<product-durableID>` -方法 2： `GET <resource-durableID>` -方法 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），而是使用资源 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>

可以使用“资源树”资源类型以及产品的持久 ID 检索特定产品中的所有资源配置。

每个资源可用的最新架构版本可能有所不同。执行资源树请求时，指定的架构版本决定了为产品中的每个资源返回哪个版本。指定的版本用作“max”版本限制，因为它返回可用于相同或更低版本的所有资源的最新架构版本。例如，如果可用的最新计划列表版本为“2022-03-01-preview3”，则响应将在资源树 GET 请求中指定“2022-03-01-preview5”时显示此版本。但是，如果请求“2022-03-01-preview2”作为资源树版本，则会返回“2022-03-01-preview2”计划列表资源，即使可用的最新版本是“2022-03-01-preview3”。建议使用每个资源的最新可用版本，以确保将更新的架构与新支持的功能一起使用。

注意

如果不知道产品的持久 ID，可以使用产品的外部 ID 通过运行 GET product?externalID=<product-externalID>&$version=<product-schema-version>来检索产品资源。此请求使用查询字符串参数，方法 3 中对此进行了详细介绍。响应包括产品的持久化 ID，可用于后续请求。

默认情况下，使用“资源树”运行 GET 调用时，将返回资源的草稿版本。但是，通过传递“targetType”查询参数，可以指定所需的目标来检索“预览”或“实时”数据。在以下示例中，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：持久 ID

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

使用特定资源的持久 ID 检索特定资源。创建资源后，持久 ID 始终保持不变，并可用于通过调用 GET 方法检索该资源的最新草稿更改。例如，以下请求使用“2022-03-01-preview3”架构版本返回此特定产品的草稿配置。

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

重要

此方法仅用于检索草稿配置。如果要检索预览或实时数据，请使用前文详述的“资源树”方法。

若要查找资源的持久 ID，可以：

使用“资源树”方法提取产品中的所有资源及其各自的持久 ID，或
检索已完成的资源配置请求的详细信息，其中包括作为请求的一部分创建或更新的所有资源的持久 ID。

请记住，“ID”属性是各自资源的持久性 ID。

方法 3：查询字符串参数

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

此方法用于查询与特定帐户关联的某些资源类型。例如，可以使用单个 GET 调用检索特定产品类型的所有产品。查询字符串参数用于查询与产品、计划或提交相关的详细信息。

此表显示了每种支持的资源类型支持的查询参数。并非所有资源类型都支持每个查询参数。请参考此表，了解当前支持的查询字符串的完整列表。

资源类型	Parameters	查询字符串示例
计划	产品`` 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>`
提交	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”参数时，它将返回相应产品或计划的配置。与“资源树”方法不同，此查询字符串参数仅返回该资源的详细信息，而非其中的所有资源。
type – 在“product”资源类型的上下文中传递“type”参数时，它将返回与帐户关联的该类型的所有产品。例如，通过指定“type=softwareAsAService”，将返回所有 SaaS 产品。
targetType – 这会返回所用资源类型的上下文中特定环境的数据。支持的“targetType”值为“草稿”、“预览”或“实时”。
$maxpagesize - 过以正整数的形式指定最大页面大小，此参数用于在查询之前提交的内容时限制搜索结果。
continuationToken – 此参数可与“$maxpagesize”参数一起使用，以查询搜索中可用的另一组结果。上一页的响应中提供了“continuationToken”值。
$version – 这是所有调用的必需参数，它指定对发出请求的响应所需的架构版本。每个资源可用的最新架构版本可能有所不同，指定的版本用作“max”版本限制。系统返回确切的架构版本（如果可用）或比请求的版本早于请求的版本。即使存在较新的架构更改，这也有助于维护代码正常运行，但为了利用最新功能，建议使用每个架构的最新可用版本。

查询提交

可以通过执行 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

示例响应：

此示例显示了与产品 ID“12345678-abcd-efgh-1234-12345678901”关联的活动提交的 GET 请求。活动的“实时”提交（submission/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"
                }
              ]
            }

创建新产品和资源

作为单个配置请求的一部分，你可以创建新资源，包括新产品。通过使用 Resource API 参考表，可以检索要创建的资源类型的架构。这可确保使用最新的架构并因此配置所有必要的属性来创建资源。

如果要创建新产品，要求因产品类型而异。因此，需要提供不同的资源。可以参考相应产品类型的相应商业市场文档，以确保在请求中配置基本要求。或者，只需使用产品资源即可发出配置请求。创建产品后，调用配置状态详细信息 API 以检索已创建的产品资源，并查找其持久 ID 以调用资源树查询 API。响应返回所创建产品类型的适用支持资源。

同样，若要在现有产品中创建新资源，还需要检索该特定资源类型的最新架构。通过查看资源依赖项，确保提供依赖资源作为配置请求的一部分。

使用架构构造资源后，了解如何发出配置请求。

修改现有产品和资源

可以使用配置有效负载提交更新。此有效负载由一个或多个资源类型组成，“$schema”属性指示所引用的资源类型。

提示

建议先检索现有资源，然后再发布更新，以确保使用最新配置。

修改资源后，了解如何发出配置请求。

配置请求

可以在同一有效负载中进行编辑和发布。若要提交配置请求，请使用配置 API 的 HTTP POST 方法。配置有效负载由指示所需更改的资源数组组成。所有编辑仅影响草稿版本，直到显式提交提交资源以发布草稿更改。发布到预览版或实时版时，请包含提交资源并指定目标环境。在提交请求之前，需要了解如何引用资源并了解其依赖项。

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

提交配置请求后，可以使用 jobID 返回配置状态对象，该对象可用于跟踪请求的进度和结果。

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

资源引用和依赖项

参考

若要在配置请求中引用现有资源，请提供资源的“$schema”类型以及资源的持久 ID。对于产品和计划，还可以通过其外部 ID 引用这些资源。

持久 ID 可以在“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"
            }

耐用ID为“product/071b135e-9faf-4ff7-b113-a3f25bb0f468”。

通过在“product”资源架构属性中设置持久性 ID，可以在下面示例的清单资源中使用该持久性 ID，如下所示：

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

产品和计划资源的外部 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",
                  ...
              }

然后，计划外部 ID“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 产品，其外部 ID 为“ds-contoso-image-resize-demo”。创建此产品后，可以使用其持久性 ID 或外部 ID 来引用此产品。

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”属性，表示正按其持久 ID 或外部 ID 引用更新的产品
“targetType”属性，表示目标环境

专门发布到实时发布时，要发布的预览提交的“ID”：

              {
                "$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" }
              }
              ]
            }

发布到实时

测试并验证预览中的更改后，可以通过发送配置请求（包含预览提交的“ID”并将“targetType”设置为“实时”）来将更改推送到“实时”。若要查找要包含在配置请求中的预览提交的“ID”，请参阅查询提交。

重要

与发布到预览版时不同，在发布到在线时，无法选择执行模块化发布。因此，请务必确保在正式发布更改前已验证预览提交。

示例请求：

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" }
              }
              ]
            }

检查请求的状态

无论配置请求中包含的资源或所做更改中包括的资源，在成功处理请求后不久，会在响应中返回 配置状态 对象。 “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 产品的配置请求的摘要详细信息。响应是配置详细信息对象，其中包含包含创建的产品资源及其持久 ID 的资源数组。

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 调用，并提供要取消的请求的作业 ID。

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”资源同步专用受众。这会同步草稿、预览和实时环境，使其具有相同的专用受众值。同步专用受众时无需提供提交资源。

若要编辑草稿受众，请使用“价格和可用性计划”资源和“privateAudiences”属性。这需要通过常规发布流程才能在“预览”和“实时”中设置值。

重要

支持的用户类型为“订阅”、“企业协议 (ea)”、“微软开发者网络（msdn）”和“租户”，但对这些类型的支持因产品类型而有所不同。如果产品支持使用多种类型的标识符来配置专用受众（例如，租户 ID 和订阅 ID），则在首次提供新的标识符类型时必须执行完整发布。在这种情况下，无法同步私人受众。

同步专用受众配置的示例请求：

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”属性更新为“已删除”来删除特定资源。只能删除从未发布过的草稿资源。此操作不能撤消。

示例请求：

在下面的示例中，已删除“基本”草稿计划。

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”属性设置为支持它的资源“已弃用”。存在各种级别的弃用。所有产品类型都支持弃用整个产品和单个计划。若要以后还原已弃用的资源，请参阅 “generallyAvailable”生命周期状态。

产品弃用的示例请求：

在下面的示例中，产品的实时提交设置为弃用。应用此更改后，它会自动发布到实时状态以生效。

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
提交	可用于触发产品的不同操作，并指示产品不区分环境的发布状态（草稿、预览和实时）。	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 以继续为市场产品/服务配置 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 访问令牌

概念

资源

持久 ID

外部 ID

API 方法

典型工作流

检索现有资源配置

方法 1：资源树

方法 2：持久 ID

方法 3：查询字符串参数

查询提交

创建新产品和资源

修改现有产品和资源

配置请求

资源引用和依赖项

参考

依赖项

提交资源

发布到预览

方法 1：发布所有草稿资源

方法 2：发布特定草稿资源（也称为模块化发布）

发布到实时

检查请求的状态

挂起请求的状态

已完成请求的摘要

取消配置请求

同步专用受众

配置潜在顾客管理

资源生命周期状态

已删除

已放弃

正式发布

资源 API 参考

每个产品类型的 API 指南

API 版本和更新

相关内容

反馈

其他资源