管理加载项提交

项目
04/06/2023

Microsoft Store 提交 API 将提供可用于管理针对应用的加载项（也称为应用内产品或 IAP）提交的方法。有关 Microsoft Store 提交 API 的介绍（包括使用 API 的先决条件），请参阅使用 Microsoft Store 服务创建和管理提交。

重要

如果使用 Microsoft Store 提交 API 创建加载项提交，请务必只使用此 API 对提交进行进一步更改，而不是在合作伙伴中心进行更改。如果使用合作伙伴中心来更改最初使用此 API 创建的提交，则无法再使用此 API 更改或完成该提交。在某些情况下，在提交过程中无法继续进行时，提交可能会处于错误状态。如果发生这种情况，你必须删除提交并创建新的提交。

管理加载项提交的方法

使用以下方法获取、创建、更新、提交或删除加载项提交。在使用这些方法之前，加载项必须已存在于你的合作伙伴中心帐户中。通过定义其产品类型和产品 ID，或者使用管理加载项中所述的 Microsoft Store 提交 API 方法，可以在合作伙伴中心创建加载项。

方法	URI	说明
GET	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	获取现有的加载项提交
GET	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/status	获取现有加载项提交的状态
POST	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions	创建新加载项提交
PUT	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}	更新现有的加载项提交
POST	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/submissions/{submissionId}/commit	提交新建或已更新的加载项提交
DELETE	https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/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/inappproducts/{id}/submissions
```
响应正文包含加载项提交资源，该资源包括新的提交 ID、共享访问签名 (SAS) URI（用于将提交的所有加载项图标上传到 Azure Blob 存储）以及所有新的提交数据（如列表和定价信息）。

注意

SAS URI 提供对 Azure 存储中的安全资源的访问权限（无需帐户密钥）。有关 SAS URI 以及借助 Azure Blob 使用这些 URI 的背景信息，请参阅共享访问签名，第 1 部分：了解 SAS 模型和共享访问签名，第 2 部分：使用 Blob 存储创建和使用 SAS。
如果要为提交添加新的图标，请准备图标并将它们添加到 ZIP 存档。
使用新提交所需的任何更改来更新加载项提交数据，并执行以下方法来更新提交。有关详细信息，请参阅更新加载项提交。
```
PUT https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/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/inappproducts/{id}/submissions/{submissionId}/commit
```
通过执行以下方法来检查提交状态。有关详细信息，请参阅获取加载项提交的状态。
```
GET https://manage.devcenter.microsoft.com/v1.0/my/inappproducts/{id}/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 页面。

数据资源

管理加载项提交的 Microsoft Store 提交 API 方法使用以下 JSON 数据资源。

加载项提交资源

此资源描述加载项提交。

{
  "id": "1152921504621243680",
  "contentType": "EMagazine",
  "keywords": [
    "books"
  ],
  "lifetime": "FiveDays",
  "listings": {
    "en": {
      "description": "English add-on description",
      "icon": {
        "fileName": "add-on-en-us-listing2.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (English)"
    },
    "ru": {
      "description": "Russian add-on description",
      "icon": {
        "fileName": "add-on-ru-listing.png",
        "fileStatus": "Uploaded"
      },
      "title": "Add-on Title (Russian)"
    }
  },
  "pricing": {
    "marketSpecificPricings": {
      "RU": "Tier3",
      "US": "Tier4",
    },
    "sales": [],
    "priceId": "Free",
    "isAdvancedPricingModel": true
  },
  "targetPublishDate": "2016-03-15T05:10:58.047Z",
  "targetPublishMode": "Immediate",
  "tag": "SampleTag",
  "visibility": "Public",
  "status": "PendingCommit",
  "statusDetails": {
    "errors": [
      {
        "code": "None",
        "details": "string"
      }
    ],
    "warnings": [
      {
        "code": "ListingOptOutWarning",
        "details": "You have removed listing language(s): []"
      }
    ],
    "certificationReports": [
      {
      }
    ]
  },
  "fileUploadUrl": "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",
  "friendlyName": "Submission 2"
}

此资源具有以下值。

Value	类型	描述
id	string	提交的 ID。此 ID 包含在 create an add-on submission、get all add-ons 和 get an add-on 请求的响应数据中。对于在合作伙伴中心中创建的提交，此 ID 也可以在合作伙伴中心提交页面的 URL 中找到。
contentType	string	加载项中提供的内容类型。这可以是以下值之一： NotSet BookDownload EMagazine ENewspaper MusicDownload MusicStream OnlineDataStorage VideoDownload VideoStream Asp OnlineDownload
关键字	array	字符串数组，其中最多包含加载项的 10 个关键字。应用可以使用这些关键字来查询加载项。
lifetime	string	加载项的生存期。这可以是以下值之一：永久 OneDay ThreeDays FiveDays OneWeek TwoWeeks OneMonth TwoMonths ThreeMonths SixMonths OneYear
listings	object	键值对字典，其中每个键为两个字母的 ISO 3166-1 二字母国家/地区代码，而每个值为含有加载项列表信息的列表资源对象。
定价	object	包含加载项的定价信息的定价资源。
targetPublishMode	string	提交的发布模式。这可以是以下值之一：即时手动 SpecificDate
targetPublishDate	string	提交的发布日期采用 ISO 8601 格式（如果 targetPublishMode 设为“SpecificDate”）。
标记	string	加载项的自定义开发人员数据（此信息之前称为 tag）。
可见性	string	加载项的可见性。这可以是以下值之一： Hidden 公用专用 NotSet
状态	字符串	提交的状态。这可以是以下值之一：无已取消 PendingCommit CommitStarted CommitFailed PendingPublication 发布已发布 PublishFailed PreProcessing PreProcessingFailed 认证 CertificationFailed 发布 ReleaseFailed
statusDetails	object	包含有关提交状态的附加详细信息的状态详细信息资源，其中包括任何错误的相关信息。
fileUploadUrl	string	用于为提交上传任何程序包的共享访问签名 (SAS) URI。如果要为提交添加新的程序包，请将包含这些程序包的 ZIP 存档上载到此 URI。有关详细信息，请参阅创建加载项提交。
friendlyName	字符串	提交的友好名称，如合作伙伴中心所示。当你创建提交时，系统会为你生成此值。

应用一览资源

此资源包含加载项的列表信息。此资源具有以下值。

Value	类型	说明
description	字符串	加载项列表的描述。
icon	object	包含加载项列表的图标数据的图标资源。
title	字符串	加载项列表的标题。

图标资源

此资源包含加载项列表的图标数据。此资源具有以下值。

Value	类型	说明
fileName	string	ZIP 存档中已为提交上载的图标文件的名称。图标必须是大小正好为 300 x 300 像素的 .png 文件。
fileStatus	string	图标文件的状态。这可以是以下值之一：无 PendingUpload 已上传 PendingDelete

定价资源

此资源包含加载项的定价信息。此资源具有以下值。

Value	类型	说明
marketSpecificPricings	object	键值对字典，其中每个键为两个字母的 ISO 3166-1 二字母国家/地区代码，而每个值为价格段。这些项表示加载项在特定市场中的自定义价格。此字典中的任何项替代 priceId 值针对特定市场所指定的基价。
销售额	array	已弃用。包含加载项销售信息的销售资源数组。
priceId	string	用于指定加载项基价的价格段。
isAdvancedPricingModel	boolean	如果为 true，你的开发人员帐户可以使用从 0.99 美元到 1999.99 美元的扩展价格段。如果为 false，你的开发人员帐户可以使用从 0.99 美元到 999.99 美元的原始价格段。有关其他价格段的详细信息，请参阅价格段。注意：此字段为只读字段。

销售资源

此资源包含加载项的销售信息。

重要

销售资源不再受支持，并且当前不能使用 Microsoft Store 提交 API 获取或修改加载项提交的销售数据。将来，我们将更新 Microsoft Store 提交 API，以引入以编程方式访问加载项提交的销售信息的新方法。

调用 GET 方法以获取加载项提交后，销售值将为空。可继续使用合作伙伴中心获取进行加载项提交的销售数据。
调用 PUT 方法以更新加载项提交时，将忽略销售值中的信息。可继续使用合作伙伴中心来更改进行加载项提交的销售数据。

此资源具有以下值。

Value	类型	说明
name	string	销售的名称。
basePriceId	string	要用于销售基价的价格段。
startDate	string	采用 ISO 8601 格式的销售的开始日期。
endDate	string	采用 ISO 8601 格式的销售的结束日期。
marketSpecificPricings	object	键值对字典，其中每个键为两个字母的 ISO 3166-1 二字母国家/地区代码，而每个值为价格段。这些项表示加载项在特定市场中的自定义价格。此字典中的任何项替代 basePriceId 值针对特定市场所指定的基价。

状态详细信息资源

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

Value	类型	说明
错误	object	包含提交的错误详细信息的状态详细信息资源数组。
warnings	object	包含提交的警告详细信息的状态详细信息资源数组。
certificationReports	object	提供对提交的认证报告数据的访问权限的认证报告资源数组。如果认证失败，可检查这些报告，获取详细信息。

状态详细信息资源

此资源包含关于提交的任何相关错误或警告的附加详细信息。此资源具有以下值。

Value	类型	说明
code	string	描述错误或警告类型的提交状态代码。
详细信息	string	包含有关问题的更多详细信息的消息。

认证报告资源

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

Value	类型	说明
date	string	报告生成的日期和时间，采用 ISO 8601 格式。
reportUrl	string	用于访问报告的 URL。

枚举

这些方法使用以下枚举。

价格段

以下值表示加载项提交的定价资源中可用的价格段。

Value	说明
基本	未设置价格段；使用加载项的基价。
NotAvailable	加载项在特定区域中不可用。
免费	加载项是免费的。
Tierxxxx	一个字符串，用于为加载项指定价格段（Tierxxxx 格式）。目前，支持以下价格段范围：如果定价资源的 isAdvancedPricingModel 值为 true，则你的帐户的可用价格段值为 Tier1012 - Tier1424。如果定价资源的 isAdvancedPricingModel 值为 false，则你的帐户的可用价格段值为 Tier2 - Tier96。若要查看可用于开发人员帐户的完整价格段表（包括与每个价格段关联的特定于市场的价格），请在合作伙伴中心前往你的任意应用提交的“定价和可用性”页面，然后单击“市场与自定义价格”部分的“查看表格”链接（对于某些开发人员帐户，此链接位于“定价”部分）。

提交状态代码

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

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

管理加载项提交

管理加载项提交的方法

创建加载项提交

代码示例

StoreBroker PowerShell 模块

数据资源

加载项提交资源

应用一览资源

图标资源

定价资源

销售资源

状态详细信息资源

状态详细信息资源

认证报告资源

枚举

价格段

提交状态代码

反馈

反馈

其他资源

管理加载项提交

管理加载项提交的方法

创建加载项提交

代码示例

StoreBroker PowerShell 模块

数据资源

加载项提交资源

应用一览资源

图标资源

定价资源

销售资源

状态详细信息资源

状态详细信息资源

认证报告资源

枚举

价格段

提交状态代码

相关主题

反馈

反馈

其他资源