用于商业市场的产品引入 API
产品引入 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 Store 提交 API 时使用的 Microsoft Entra 访问令牌。
将 Microsoft Entra 应用程序与合作伙伴中心帐户相关联
若要使用产品引入 API，必须将 Microsoft Entra 应用程序与合作伙伴中心帐户相关联，检索应用程序的租户 ID 和客户端 ID，并生成密钥。 Microsoft Entra 应用程序表示要从中调用产品引入 API 的应用或服务。 需要租户 ID、客户端 ID 和密钥才能获取要传递给 API 的 Microsoft Entra 访问令牌。
注意
此任务只需执行一次。 拥有租户 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 中的 tenant_id 值以及 client_id 和 client_secret 参数，请指定在上一部分中从合作伙伴中心中为应用程序检索的租户 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：durable-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 |
典型工作流
若要更新现有资源，典型的工作流如下：
* 创建新资源时可以应用相同的工作流，但不是检索资源（步骤 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”参数时，它将返回相应产品或计划的配置。 与“resource-tree”方法不同，此查询字符串参数将仅返回该资源的详细信息，而不是其中的所有资源。
- type – 在“product”资源类型的上下文中传递“type”参数时，它将返回与帐户关联的该类型的所有产品。 例如，通过指定“type=softwareAsAService”，将返回所有 SaaS 产品。
- targetType – 这会返回所用资源类型的上下文中特定环境的数据。 支持的“targetType”值为“draft”、“preview”或“live”。
- $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 请求。 活动“实时”提交（提交/12345678-abcd-efgh-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”。
然后，可以在下面的列表资源示例中使用持久 ID，方法是在“product”资源架构属性中设置它，如下所示：
{
"$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"}
...
},
}]
}
提交资源
如果发布到“预览”或“live”，请在请求中包含提交资源，其中包含：
- “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”设置为“live”来将更改推送到实时。 若要查找要包含在配置请求中的预览提交的“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”属性。 这需要通过常规发布流，以便以预览和实时方式设置值。
重要
支持的受众类型为“subscription”、“ea”、“msdn”和“tenant”，但对这些受众的支持因产品类型而异。 如果产品支持使用多种类型的标识符来配置专用受众（例如，租户 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”属性更新为“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”属性设置为支持它的资源“已弃用”。 存在各种级别的弃用。 所有产品类型都支持弃用整个产品和单个计划。 若要以后还原已弃用的资源，请参阅 “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
每个产品类型的 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 发布 |
后续步骤
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈