管理软件包飞行提交

2025-06-10

Microsoft Store 提交 API 提供了可用于管理应用的软件包飞行提交的方法，包括逐步发布软件包。有关 Microsoft 应用商店提交 API 的简介，包括使用 API 的先决条件，请参阅使用 Microsoft 应用商店服务创建和管理提交。

重要

如果使用 Microsoft Store 提交 API 为包航班创建提交，请确保仅使用 API 进行进一步更改，而不是使用合作伙伴中心。如果使用仪表板更改最初使用 API 创建的提交，将无法再使用 API 更改或提交该提交。在某些情况下，提交可能处于错误状态，无法继续提交过程。如果发生这种情况，则必须删除提交并创建新提交。

管理软件包试运行提交的方法

使用以下方法获取、创建、更新、提交或删除软件包航班提交。在使用这些方法之前，“包飞行”必须已经存在于合作伙伴中心。可以在合作伙伴中心中创建包飞行，或使用中描述的 Microsoft Store 提交 API 方法进行创建，详见管理包飞行。

方法	URI	DESCRIPTION
获取	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}	获取现有软件包外部测试版提交
获取	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/status	获取现有包航班提交的状态
帖子	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions	创建新的软件包测试提交
放置	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}	更新现有包航班提交
帖子	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/commit	提交新的或更新的软件包外部测试版提交
删除	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}	删除软件包试用版提交

创建包裹飞行提交

创建航班套餐的提交，请遵循此过程。

如果尚未这样做，请完成使用 Microsoft 应用商店服务创建和管理提交中所述的先决条件，包括将 Azure AD 应用程序与合作伙伴中心帐户关联并获取客户端 ID 和密钥。只需执行一次;获取客户端 ID 和密钥后，可以随时重复使用它们，以创建新的 Azure AD 访问令牌。
获取 Azure AD 访问令牌。在 Microsoft Store 提交 API 中，必须将此访问令牌传递给相关方法。获取访问令牌后，在它到期前，你有 60 分钟的使用时间。令牌过期后，可以获取一个新令牌。
通过在 Microsoft 应用商店提交 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 存储配合使用的背景信息，请参阅共享访问签名，第 1 部分：了解 SAS 模型和共享访问签名，第 2 部分：创建 SAS 并将其与 Blob 存储配合使用。
如果要为提交添加新包，准备包并将其添加到 ZIP 存档。
使用新提交的任何所需更改修改外部测试版提交数据，并执行以下方法来更新软件包外部测试版提交。
```
PUT https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}
```
注释

如果要为提交添加新包，请确保更新提交数据以引用 ZIP 存档中这些文件的名称和相对路径。
如果要为提交添加新包，请使用前面调用的 POST 方法的响应正文中提供的 SAS URI 将 ZIP 存档上传到 Azure Blob 存储。可以使用不同的 Azure 库在各种平台上执行此操作，包括：
- 适用于 .NET 的 Azure 存储客户端库
- 用于 Java 的 Azure 存储 SDK
- 用于 Python 的 Azure 存储 SDK
以下 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
```
若要确认提交状态，请查看响应正文中的状态值。如果请求成功，此值应从 CommitStarted 更改为 PreProcessing;如果请求中存在错误，则此值应更改为 CommitFailed。如果存在错误，statusDetails 字段包含有关错误的更多详细信息。
提交成功完成后，提交将发送到应用商店进行引入。可以使用以前的方法或访问合作伙伴中心，继续监视提交进度。

代码示例

以下文章提供了详细的代码示例，演示如何在几种不同的编程语言中创建包飞行提交：

StoreBroker PowerShell 模块

作为直接调用 Microsoft 应用商店提交 API 的替代方法，我们还提供一个开源 PowerShell 模块，该模块在 API 顶部实现命令行接口。此模块名为 StoreBroker。可以使用此模块从命令行管理应用程序、航班和加载项的提交，而不是直接调用 Microsoft Store 提交 API。您也可以查看源代码以了解如何调用此 API 的更多示例。 StoreBroker 模块在 Microsoft 中被主动用作许多第一方应用程序提交到应用商店的主要方式。

有关详细信息，请参阅 GitHub上的 StoreBroker 页。

管理软件包飞行提交的逐步推出

你可以在应用程序包飞行提交中逐步向一部分 Windows 10 和 Windows 11 客户推送更新的程序包。这样，你可以监视特定包的反馈和分析数据，以确保在更广泛地推出更新之前对更新充满信心。可以更改已发布提交的推出百分比（或停止更新），而无需创建新的提交。有关详细信息，包括有关如何在合作伙伴中心中启用和管理逐步软件包推出的说明，请参阅本文章。

若要以编程方式为软件包外部测试版提交启用逐步软件包推出，请使用 Microsoft 应用商店提交 API 中的方法遵循此过程：

创建软件包航班提交或获取软件包航班提交。
在响应数据中，找到 packageRollout 资源，将 isPackageRollout 字段设置为 true，并将 packageRolloutPercentage 字段设置为应获取更新包的应用客户的百分比。
将更新的软件包航班提交数据传递到更新软件包航班提交方法。

为软件包试运行提交启用逐步推出后，可以使用以下方法以编程方式获取、更新、暂停或完成逐步推出。

方法	URI	DESCRIPTION
获取	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/packagerollout	获取软件包飞行提交的逐步推出信息
帖子	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/updatepackagerolloutpercentage	更新包飞行提交的逐步推出百分比
帖子	https://manage.devcenter.microsoft.com/v1.0/my/applications/{applicationId}/flights/{flightId}/submissions/{submissionId}/haltpackagerollout	停止软件包外部测试版提交的逐步推出
帖子	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."
}

此资源具有以下值。

价值	类型	DESCRIPTION
id	字符串	提交的 ID。
航班编号	字符串	提交与之关联的软件包飞行的 ID。
地位	字符串	提交的当前状态。这可以是以下值之一：没有已取消待提交提交已开始提交失败待发表出版已发布发布失败预处理预处理失败认证认证失败释放发布失败
状态详情	物体	包含有关提交状态的附加详细信息的状态详细信息资源，其中包括任何错误的相关信息。
航班套餐	数组	包含航班包资源，这些资源提供有关提交中每个包的详细信息。
包裹配送选项	物体	软件包递送选项资源，其中包含提交的逐步软件包推出和强制更新设置。
文件上传网址	字符串	用于上传提交任意包的共享访问签名 URI (SAS)。如果要为提交添加新包，请将包含包的 ZIP 存档上传到此 URI。有关详细信息，请参阅创建软件包航班提交。
目标发布模式	字符串	提交时的发布模式。这可以是以下值之一：立刻手动具体日期
目标发布日期	字符串	如果 targetPublishMode 设置为 SpecificDate，则提交的发布日期应采用 ISO 8601 格式。
认证说明	字符串	为认证测试人员提供其他信息，例如测试帐户凭据和访问和验证功能的步骤。有关详细信息，请参阅认证说明。

状态详情资源

此资源包含有关提交状态的其他详细信息。此资源具有以下值。

价值	类型	DESCRIPTION
错误	物体	一个由包含提交错误详细信息的状态详细信息资源组成的数组。
警告	物体	状态详细信息资源数组，包含与提交相关的警告详细信息。
认证报告	物体	一系列认证报告资源，提供对提交的认证报告数据的访问权限。如果认证失败，可以检查这些报告以了解详细信息。

状态详细信息资源

此资源包含有关提交时出现的相关错误或警告的更多信息。此资源具有以下值。

价值	类型	DESCRIPTION
代码	字符串	描述错误或警告类型的提交状态代码。
详情	字符串	一条消息，其中包含有关该问题的更多详细信息。

认证报告资源

此资源提供对提交的认证报告数据的访问权限。此资源具有以下值。

价值	类型	DESCRIPTION
日期	字符串	以 ISO 8601 格式生成报表的日期和时间。
报告网址	字符串	可访问报表的 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 在内的值。其他值由合作伙伴中心填充。

价值	类型	DESCRIPTION
文件名	字符串	包的名称。
文件状态	字符串	包的状态。这可以是以下值之一：没有待上传已上传待删除
id	字符串	用于唯一标识包裹的ID。合作伙伴中心使用此值。
版本	字符串	应用包的版本。有关详细信息，请参阅包版本号。
建筑	字符串	应用包的体系结构（例如 ARM）。
语言	数组	应用支持的语言的语言代码数组。如需更多信息，请参阅如需更多信息，请参阅支持的语言。
能力	数组	包所需的功能数组。有关功能的详细信息，请参阅应用功能声明。
最低DirectX版本	字符串	应用包支持的最低 DirectX 版本。这只能针对面向 Windows 8.x 的应用进行设置;对于面向其他版本的应用，将忽略它。这可以是以下值之一：没有 DirectX93 DirectX100
最小系统内存	字符串	应用包所需的最小 RAM。这只能针对面向 Windows 8.x 的应用进行设置;对于面向其他版本的应用，将忽略它。这可以是以下值之一：没有 Memory2GB

包裹投递选项资源

此资源包含提交的逐步程序包推出和强制更新设置。

{
  "packageDeliveryOptions": {
    "packageRollout": {
        "isPackageRollout": false,
        "packageRolloutPercentage": 0.0,
        "packageRolloutStatus": "PackageRolloutNotStarted",
        "fallbackSubmissionId": "0"
    },
    "isMandatoryUpdate": false,
    "mandatoryUpdateEffectiveDate": "1601-01-01T00:00:00.0000000Z"
  },
}

此资源具有以下值。

价值	类型	DESCRIPTION
packageRollout	物体	一个包含用于提交的逐步软件包推出设置的软件包推出资源。
是否强制更新	布尔	指示是否要将此提交中的包视为自安装应用更新必需的。有关自安装应用更新的必需包的详细信息，请参阅下载和安装应用的包更新。
强制更新生效日期	日期	此提交中的包变为强制性的日期和时间，采用 ISO 8601 格式和 UTC 时区。

程序包发布资源

此资源包含用于提交的逐步程序包推出设置。此资源具有以下值。

价值	类型	DESCRIPTION
isPackageRollout	布尔	指示是否为提交内容启用了分阶段软件包发布。
软件包发布百分比	漂浮	将在逐步推出中接收程序包的用户百分比。
软件包部署状态	字符串	下列字符串之一，表示逐步发布软件包的状态：软件包部署未开始包裹正在部署中软件包部署完成软件包部署停止
fallbackSubmissionId	字符串	不会收到逐步推出程序包的客户将接收的提交 ID。

注释

packageRolloutStatus 和 fallbackSubmissionId 值由合作伙伴中心分配，不应由开发人员设置。如果在请求正文中包含这些值，这些值将被忽略。

枚举

这些方法使用以下枚举。

提交状态代码

以下代码表示提交的状态。

代码	DESCRIPTION
没有	未指定任何代码。
无效的存档	包含包的 ZIP 存档无效或存档格式无法识别。
MissingFiles	ZIP 存档不包含提交数据中列出的所有文件，或者它们位于存档中的错误位置。
包验证失败	提交中的一个或多个包未能验证。
无效的参数值	请求正文中的一个参数无效。
无效操作	您尝试的操作是无效的。
无效状态	您尝试的操作在软件包飞行的当前状态下无效。
资源未找到	找不到指定的软件包飞行。
服务错误	内部服务错误阻止请求成功。再次尝试请求。
列表退出警告	开发人员从以前的提交中删除了一个列表，或者不包含程序包支持的列表信息。
列表选择加入警告	开发人员添加了一个列表。
UpdateOnlyWarning	开发人员正在尝试插入仅具有更新支持的内容。
其他	提交处于未被识别或未分类的状态。
软件包验证警告	包验证过程导致出现警告。

通过

管理软件包飞行提交

管理软件包试运行提交的方法

创建包裹飞行提交

代码示例

StoreBroker PowerShell 模块

管理软件包飞行提交的逐步推出

数据资源

航班提交资源

状态详情资源

状态详细信息资源

认证报告资源

航班包资源

包裹投递选项资源

程序包发布资源

枚举

提交状态代码

相关主题

反馈

其他资源