管理软件包外部测试版提交

项目
07/05/2024

Microsoft应用商店提交 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 应用商店提交 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 应用商店提交 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存储提交 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。
状态	字符串	提交的状态。这可以是以下值之一：无已取消 PendingCommit CommitStarted CommitFailed PendingPublication 发布已发布 PublishFailed PreProcessing PreProcessingFailed 认证 CertificationFailed 发布 ReleaseFailed
statusDetails	object	包含有关提交状态的附加详细信息的状态详细信息资源，其中包括任何错误的相关信息。
flightPackages	array	包含提供提交中每个包的详细信息的外部测试版包资源。
packageDeliveryOptions	object	包传递选项资源，其中包含提交的逐步软件包推出和强制更新设置。
fileUploadUrl	string	用于为提交上传任何程序包的共享访问签名 (SAS) URI。如果要为提交添加新的程序包，请将包含这些程序包的 ZIP 存档上载到此 URI。有关详细信息，请参阅创建软件包外部测试版提交。
targetPublishMode	string	提交的发布模式。这可以是以下值之一：即时手动 SpecificDate
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 值。其他值由合作伙伴中心进行填充。

值	类型	说明
fileName	string	包的名称。
fileStatus	string	包的状态。这可以是以下值之一：无 PendingUpload 已上传 PendingDelete
id	string	唯一标识包的 ID。此值由合作伙伴中心使用。
版本	string	应用包的版本。有关详细信息，请参阅包版本号。
architecture	string	应用包的体系结构（例如 ARM）。
语言	array	应用支持的语言的语言代码数组。有关详细信息，请参阅支持的语言。
功能	array	包所需的功能数组。有关功能的详细信息，请参阅应用功能声明。
minimumDirectXVersion	string	应用包支持的最低 DirectX 版本。这只能针对面向 Windows 8.x 的应用进行设置;对于面向其他版本的应用，将忽略它。这可以是以下值之一：无 DirectX93 DirectX100
minimumSystemRam	string	应用包所需的最小 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"
  },
}

此资源具有以下值。

Value	类型	描述
packageRollout	object	包含提交的逐步软件包推出设置的包推出资源。
isMandatoryUpdate	boolean	指示是否要将此提交中的包视为自安装应用更新必需的。有关自安装应用更新的必需包的详细信息，请参阅下载和安装应用的程序包更新。
mandatoryUpdateEffectiveDate	date	此提交中的包变为强制性的日期和时间，采用 ISO 8601 格式和 UTC 时区。

包推出资源

此资源包含提交的逐步软件包推出设置。此资源具有以下值。

Value	类型	描述
isPackageRollout	boolean	指示是否为提交启用了逐步软件包推出。
packageRolloutPercentage	float	将在逐步推出中接收程序包的用户百分比。
packageRolloutStatus	string	以下字符串之一，指示逐步推出包的状态： PackageRolloutNotStarted PackageRolloutInProgress PackageRolloutComplete PackageRolloutStopped
fallbackSubmissionId	string	不会获取逐步推出包的客户将收到的提交的 ID。

注意

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

枚举

这些方法使用以下枚举。

提交状态代码

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

代码	说明
无	未指定任何代码。
InvalidArchive	包含程序包的 ZIP 存档无效或具有无法识别的存档格式。
MissingFiles	ZIP 存档未包含提交数据中列出的所有文件，或者它们位于存档中的错误位置。
PackageValidationFailed	提交中的一个或多个程序包验证失败。
InvalidParameterValue	请求正文中的某一个参数无效。
InvalidOperation	所尝试的操作无效。
InvalidState	所尝试的操作对当前状态的软件包外部测试版无效。
ResourceNotFound	找不到指定的软件包外部测试版。
ServiceError	导致请求失败的内部服务错误。重新尝试请求。
ListingOptOutWarning	开发人员已从以前的提交中删除了某个列表，或者未包含程序包支持的列表信息。
ListingOptInWarning	开发人员添加了一个列表。
UpdateOnlyWarning	开发人员正在尝试插入仅具有更新支持的某些内容。
其他	提交处于无法识别或未分类的状态。
PackageValidationWarning	程序包验证过程导致出现警告。

通过

管理软件包外部测试版提交

管理软件包外部测试版提交的方法

创建软件包外部测试版提交

代码示例

StoreBroker PowerShell 模块

管理软件包外部测试版提交的逐步软件包推出

数据资源

外部测试版提交资源

状态详细信息资源

状态详细信息资源

认证报告资源

外部测试版包资源

程序包传递选项资源

包推出资源

枚举

提交状态代码

相关主题

反馈

其他资源