管理软件包外部测试版提交
Microsoft Store 提交 API 提供可用于管理针对应用的软件包外部测试版提交的方法，包括逐步软件包推出。 有关 Microsoft Store 提交 API 的介绍（包括使用 API 的先决条件），请参阅使用 Microsoft Store 服务创建和管理提交。
重要
如果使用 Microsoft Store 提交 API 创建程序包外部测试版提交，请务必只使用此 API 而非合作伙伴中心对提交进行进一步更改。 如果你使用仪表板更改你最初使用此 API 创建的提交，则将无法再使用此 API 更改或提交该提交。 在某些情况下，在提交过程中无法继续进行时，提交可能会处于错误状态。 如果发生这种情况，你必须删除提交并创建新的提交。
管理软件包外部测试版提交的方法
使用以下方法获取、创建、更新、提交或删除软件包外部测试版提交。 在使用这些方法之前，程序包外部测试版必须已存在于合作伙伴中心中。 在合作伙伴中心，或者使用管理软件包外部测试版中所述的 Microsoft Store 提交 API 方法，可以创建软件包外部测试版。
| 方法 | URI | 说明 |
|---|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | 获取现有软件包外部测试版提交 |
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status | 获取现有软件包外部测试版提交的状态 |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions | 创建新的软件包外部测试版提交 |
| PUT | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | 更新现有软件包外部测试版提交 |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit | 提交新的或更新的软件包外部测试版提交 |
| DELETE | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId} | 删除软件包外部测试版提交 |
创建软件包外部测试版提交
若要创建软件包外部测试版提交，请遵循此过程。
如果尚未执行此操作，请完成使用 Microsoft Store 服务创建和管理提交中所述的先决条件，包括将 Azure AD 应用程序与合作伙伴中心帐户相关联并获取客户端 ID 和密钥。 你只需执行此操作一次；有了客户端 ID 和密钥后，当你需要创建新的 Azure AD 访问令牌时，可以随时重复使用它们。
获取 Azure AD 访问令牌。 在 Microsoft Store 提交 API 中，必须将此访问令牌传递给相关方法。 获取访问令牌后，在它到期前，你有 60 分钟的使用时间。 该令牌到期后，可以获取新的令牌。
通过执行 Microsoft Store 提交 API 中的以下方法创建软件包外部测试版提交。 此方法创建新的正在进行的提交，这是你上次发布的提交的副本。
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions响应正文包含外部测试版提交资源（包括新提交的 ID、用于将提交的任何程序包上传到 Azure Blob 存储的共享访问签名 (SAS) URI）和新提交的数据（包括所有应用一览和定价信息）。
注意
SAS URI 提供对 Azure 存储中的安全资源的访问权限（无需帐户密钥）。 有关 SAS URI 以及借助 Azure Blob 使用这些 URI 的背景信息，请参阅共享访问签名，第 1 部分：了解 SAS 模型和共享访问签名，第 2 部分：使用 Blob 存储创建和使用 SAS。
若要为提交添加新的软件包，请准备软件包并将它们添加到 ZIP 存档。
使用新提交所需的任何更改修订外部测试版提交数据，并执行以下方法来更新软件包外部测试版提交。
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}注意
如果要为提交添加新的软件包，请确保更新提交数据以便在 ZIP 存档中引用这些文件的名称和相对路径。
如果要为提交添加新包，请使用 SAS URI 将 ZIP 存档上载到 Azure Blob 存储，该 URI 已在之前调用的 POST 方法的响应正文中提供。 你可以使用不同的 Azure 库在多个平台上进行此操作，包括：
以下 C# 代码示例演示了如何在用于 .NET 的 Azure 存储客户端库中使用 CloudBlockBlob 类将 ZIP 存档上传到 Azure Blob 存储。 此示例假定 ZIP 存档已写入流对象。
string sasUrl = "https://productingestionbin1.blob.core.windows.net/ingestion/26920f66-b592-4439-9a9d-fb0f014902ec?sv=2014-02-14&sr=b&sig=usAN0kNFNnYE2tGQBI%2BARQWejX1Guiz7hdFtRhyK%2Bog%3D&se=2016-06-17T20:45:51Z&sp=rwl"; Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob blockBob = new Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob(new System.Uri(sasUrl)); await blockBob.UploadFromStreamAsync(stream);通过执行以下方法确认软件包外部测试版提交。 这将向合作伙伴中心发出警报：已完成提交，更新现在应该应用到了帐户。
POST https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit通过执行以下方法来检查提交状态以获取软件包外部测试版提交的状态。
GET https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status若要确认提交状态，请查看响应正文中的 status 值。 如果请求成功，此值应该从 CommitStarted 更改为 PreProcessing；如果请求中存在错误，此值应该更改为 CommitFailed。 如果存在错误，statusDetails 字段将包含有关错误的更多详细信息。
在提交成功完成之后，提交会发送至应用商店以供引入。 可以通过使用前面的方法，或者通过访问合作伙伴中心，继续监视提交进度。
代码示例
下文中提供了详细的代码示例，演示如何以不同的多种编程语言创建软件包外部测试版提交。
StoreBroker PowerShell 模块
除了直接调用 Microsoft Store 提交 API 的方式外，我们还提供在该 API 之上实现命令行界面的开源 PowerShell 模块。 此模块称为 StoreBroker。 你可以使用此模块从命令行管理你的应用、外部测试版和加载项提交，而不是通过直接调用 Microsoft Store 提交 API，或者你可以浏览源以查看更多有关如何调用此 API 的示例。 在 Microsoft 内，StoreBroker 模块作为将许多第一方应用程序提交到 Microsoft Store 的主要方式被频繁使用。
有关详细信息，请参阅我们 GitHub 上的 StoreBroker 页面。
管理软件包外部测试版提交的逐步软件包推出
你可以逐步在软件包外部测试版提交中向应用Windows 10和Windows 11的一定比例的客户推出更新的程序包。 这使你可以监视特定程序包的反馈和分析数据，从而确保在更广泛地推出更新前对此更新无虑。 可更改已发布提交的推出百分比（或终止更新），而无需创建新提交。 有关详细信息，包括有关如何在合作伙伴中心中启用和管理逐步软件包推出的说明，请参阅本文章。
若要以编程方式启用软件包外部测试版提交的逐步软件包推出，请遵循此过程使用 Microsoft Store 提交 API 中的以下方法：
- 创建软件包外部测试版提交或获取软件包外部测试版提交。
- 在响应数据中，找到 packageRollout 资源，将“isPackageRollout”字段设置为 true，然后将“packageRolloutPercentage”字段设置为应获取已更新的软件包的应用客户百分比。
- 将已更新的软件包外部测试版提交数据传递到更新软件包外部测试版提交方法。
针对软件包外部测试版提交启用逐步软件包推出后，你可以使用以下方法以编程方式获取、更新、终止或完成逐步推出。
| 方法 | URI | 说明 |
|---|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout | 获取软件包外部测试版提交的逐步推出信息 |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage | 更新软件包外部测试版提交的逐步推出百分比 |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout | 终止软件包外部测试版提交的逐步推出 |
| POST | https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/finalizepackagerollout | 完成软件包外部测试版提交的逐步推出 |
数据资源
管理软件包外部测试版提交的 Microsoft Store 提交 API 方法使用以下 JSON 数据资源。
外部测试版提交资源
此资源描述了软件包外部测试版提交。
{
"id": "1152921504621243649",
"flightId": "cd2e368a-0da5-4026-9f34-0e7934bc6f23",
"status": "PendingCommit",
"statusDetails": {
"errors": [],
"warnings": [],
"certificationReports": []
},
"flightPackages": [
{
"fileName": "newPackage.appx",
"fileStatus": "PendingUpload",
"id": "",
"version": "1.0.0.0",
"languages": ["en-us"],
"capabilities": [],
"minimumDirectXVersion": "None",
"minimumSystemRam": "None"
}
],
"packageDeliveryOptions": {
"packageRollout": {
"isPackageRollout": false,
"packageRolloutPercentage": 0.0,
"packageRolloutStatus": "PackageRolloutNotStarted",
"fallbackSubmissionId": "0"
},
"isMandatoryUpdate": false,
"mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
},
"fileUploadUrl": "https://productingestionbin1.blob.core.windows.net/ingestion/8b389577-5d5e-4cbe-a744-1ff2e97a9eb8?sv=2014-02-14&sr=b&sig=wgMCQPjPDkuuxNLkeG35rfHaMToebCxBNMPw7WABdXU%3D&se=2016-06-17T21:29:44Z&sp=rwl",
"targetPublishMode": "Immediate",
"targetPublishDate": "",
"notesForCertification": "No special steps are required for certification of this app."
}
此资源具有以下值。
| Value | 类型 | 说明 |
|---|---|---|
| id | string | 提交的 ID。 |
| flightId | string | 提交相关联的软件包外部测试版的 ID。 |
| 状态 | 字符串 | 提交的状态。 这可以是以下值之一：
|
| statusDetails | object | 包含有关提交状态的附加详细信息的状态详细信息资源，其中包括任何错误的相关信息。 |
| flightPackages | array | 包含提供提交中关于每个程序包详细信息的软件包外部测试版资源。 |
| packageDeliveryOptions | object | 包含提交的逐步软件包推出和强制更新设置的软件包递送选项资源。 |
| fileUploadUrl | string | 用于为提交上传任何程序包的共享访问签名 (SAS) URI。 如果要为提交添加新的程序包，请将包含这些程序包的 ZIP 存档上载到此 URI。 有关详细信息，请参阅创建软件包外部测试版提交。 |
| targetPublishMode | string | 提交的发布模式。 这可以是以下值之一：
|
| targetPublishDate | string | 提交的发布日期采用 ISO 8601 格式（如果 targetPublishMode 设为“SpecificDate”）。 |
| notesForCertification | string | 提供认证测试人员的其他信息，例如测试帐户凭据以及访问和验证功能的步骤。 有关详细信息，请参阅认证说明。 |
状态详细信息资源
此资源包含有关提交状态的附加详细信息。 此资源具有以下值。
| Value | 类型 | 说明 |
|---|---|---|
| 错误 | object | 包含提交的错误详细信息的状态详细信息资源数组。 |
| warnings | object | 包含提交的警告详细信息的状态详细信息资源数组。 |
| certificationReports | object | 提供对提交的认证报告数据的访问权限的认证报告资源数组。 如果认证失败，可检查这些报告，获取详细信息。 |
状态详细信息资源
此资源包含关于提交的任何相关错误或警告的附加详细信息。 此资源具有以下值。
| Value | 类型 | 说明 |
|---|---|---|
| code | string | 描述错误或警告类型的提交状态代码。 |
| 详细信息 | string | 包含有关问题的更多详细信息的消息。 |
认证报告资源
此资源提供对提交的认证报告数据的访问权限。 此资源具有以下值。
| Value | 类型 | 说明 |
|---|---|---|
| date | string | 报告生成的日期和时间，采用 ISO 8601 格式。 |
| reportUrl | string | 用于访问报告的 URL。 |
软件包外部测试版资源
此资源提供有关提交中的程序包的详细信息。
{
"flightPackages": [
{
"fileName": "newPackage.appx",
"fileStatus": "PendingUpload",
"id": "",
"version": "1.0.0.0",
"languages": ["en-us"],
"capabilities": [],
"minimumDirectXVersion": "None",
"minimumSystemRam": "None"
}
],
}
此资源具有以下值。
注意
当调用更新应用提交方法时，请求正文中仅需要此对象的 fileName、fileStatus、minimumDirectXVersion 和 minimumSystemRam 值。 其他值由合作伙伴中心进行填充。
| Value | 类型 | 说明 |
|---|---|---|
| fileName | string | 包的名称。 |
| fileStatus | string | 程序包的状态。 这可以是以下值之一：
|
| id | string | 唯一标识程序包的 ID。 此值由合作伙伴中心使用。 |
| 版本 | string | 应用包的版本。 有关详细信息，请参阅程序包版本编号。 |
| 体系结构 | string | 应用包的体系结构（例如 ARM）。 |
| 语言 | array | 语言代码数组，用于指示应用支持的语言。 有关详细信息，请参阅支持的语言。 |
| capabilities | array | 程序包所需的功能数组。 有关功能的详细信息，请参阅应用功能声明。 |
| minimumDirectXVersion | string | 应用包支持的最低 DirectX 版本。 这可以仅针对面向 Windows 8.x 的应用进行设置；对于面向其他版本的应用，它将忽略。 这可以是以下值之一：
|
| minimumSystemRam | string | 应用包所需的最小 RAM。 这可以仅针对面向 Windows 8.x 的应用进行设置；对于面向其他版本的应用，它将忽略。 这可以是以下值之一：
|
软件包递送选项资源
此资源包含提交的逐步软件包推出和强制更新设置。
{
"packageDeliveryOptions": {
"packageRollout": {
"isPackageRollout": false,
"packageRolloutPercentage": 0.0,
"packageRolloutStatus": "PackageRolloutNotStarted",
"fallbackSubmissionId": "0"
},
"isMandatoryUpdate": false,
"mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
},
}
此资源具有以下值。
| Value | 类型 | 说明 |
|---|---|---|
| packageRollout | object | 包含提交的逐步软件包推出设置的软件包推出资源。 |
| isMandatoryUpdate | boolean | 指示是否要将此提交中的软件包视为对自行安装的应用更新强制。 有关自行安装的应用更新的强制软件包的详细信息，请参阅为应用下载并安装包更新。 |
| mandatoryUpdateEffectiveDate | date | 此提交中的软件包变为强制的日期和时间，采用 ISO 8601 格式和 UTC 时区。 |
软件包推出资源
此资源包含提交的逐步软件包推出设置。 此资源具有以下值。
| Value | 类型 | 说明 |
|---|---|---|
| isPackageRollout | boolean | 指示是否为提交启用逐步软件包推出。 |
| packageRolloutPercentage | FLOAT | 将在逐步推出中收到软件包的用户百分比。 |
| packageRolloutStatus | string | 以下指示逐步软件包推出状态的字符串之一：
|
| fallbackSubmissionId | string | 将由不获取逐步推出软件包的客户接收的提交 ID。 |
注意
packageRolloutStatus 值和 fallbackSubmissionId 值由合作伙伴中心分配，但不是由开发人员设置。 如果已将这些值包括在请求正文中，则将忽略这些值。
枚举
这些方法使用以下枚举。
提交状态代码
以下代码表示提交的状态。
| 代码 | 说明 |
|---|---|
| 无 | 未指定任何代码。 |
| InvalidArchive | 包含程序包的 ZIP 存档无效或具有无法识别的存档格式。 |
| MissingFiles | ZIP 存档未包含提交数据中列出的所有文件，或者它们位于存档中的错误位置。 |
| PackageValidationFailed | 提交中的一个或多个程序包验证失败。 |
| InvalidParameterValue | 请求正文中的某一个参数无效。 |
| InvalidOperation | 所尝试的操作无效。 |
| InvalidState | 所尝试的操作对当前状态的软件包外部测试版无效。 |
| ResourceNotFound | 找不到指定的软件包外部测试版。 |
| ServiceError | 导致请求失败的内部服务错误。 重新尝试请求。 |
| ListingOptOutWarning | 开发人员已从以前的提交中删除了某个列表，或者未包含程序包支持的列表信息。 |
| ListingOptInWarning | 开发人员添加了一个列表。 |
| UpdateOnlyWarning | 开发人员正在尝试插入仅具有更新支持的某些内容。 |
| 其他 | 提交处于无法识别或未分类的状态。 |
| PackageValidationWarning | 程序包验证过程导致出现警告。 |
相关主题
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈