通过

存储资源

  • 项目

注意

Microsoft Store 资源仅对封闭 Beta 版参与者可用。 有关参与封闭 beta 或开放 beta 计划的信息，请联系你的客户经理。

在 beta 版期间，所有 Store 编程元素和文档都可能会更改。

使用 Store 资源管理用户拥有的存储。 可以添加存储、获取特定存储或获取用户拥有的所有存储。 阅读详细信息。

基 URI

下面是将 模板 追加到的基 URI。

https://content.api.ads.microsoft.com/v9.1/bmc

例如，若要添加存储或获取用户拥有的存储的列表，请使用以下终结点：

https://content.api.ads.microsoft.com/v9.1/bmc/stores

模板

这些是追加到 基 URI 以创建 HTTP 终结点的模板。

/stores 模板

HTTP 谓词 说明 资源
POST 添加存储。 以下限制适用，并随时可能更改：
  • 客户最多可添加 14 个指定同一商店 URL 的商店。
  • 客户最多可添加 1,024 家商店。
 请求： StoreCreate
响应： 存储
GET 获取用户拥有的存储的列表。 请求：不适用
响应： StoreCollection

/stores/{merchantId} 模板

HTTP 谓词 说明 资源
GET 获取指定的存储区。 设置为 {merchantId} 要获取的存储的 ID。 请求：不适用
响应： 存储

查询参数

请求可能包括以下查询参数：

参数 说明
干运行 可选。 用于测试或调试应用程序。 包含此参数的调用不会影响生产数据， (存储不会) 添加;但是，响应将包含调用生成的任何错误。

使用此参数时，请考虑以下限制。
  • 添加操作不会返回 ID。
  • 该服务不会生成或返回辅助错误消息，例如数据质量、编辑问题和与数据库相关的验证。
有关测试应用程序的详细信息，请参阅 沙盒。

标题

下面是请求和响应标头。

头 说明
AuthenticationToken 请求标头。

将此标头设置为 OAuth 访问令牌。 有关获取访问令牌的信息，请参阅 对凭据进行身份验证。
Content-Type 请求标头。

所有 POST 请求都必须指定此标头，并且必须将其设置为 application/json。
CustomerAccountId 请求标头。

代表标头中指定的客户管理的任何帐户的帐户 ID CustomerId 。 指定哪个帐户并不重要。 仅当代表客户管理帐户时，才指定此标头。
CustomerId 请求标头。

你管理的商店的客户的客户 ID。 仅当代表客户管理应用商店时，才指定此标头。 如果设置此标头，还必须设置 CustomerAccountId 标头。
DeveloperToken 请求标头。

客户端应用程序的开发人员令牌。 每个请求都必须包含此标头。 有关获取令牌的信息，请参阅 是否有 Microsoft Advertising 凭据和开发人员令牌？
WebRequestActivityId 响应标头。

包含请求详细信息的日志条目的 ID。 如果发生错误，应始终捕获此 ID。 如果无法确定和解决问题，请包含此 ID 以及你向支持团队提供的其他信息。

请求和响应对象

下面是 API 使用的请求和响应对象。

Object 说明
错误 定义错误。
ErrorResponse 定义顶级错误对象。
存储区 在 Microsoft 商家中心定义商店。
StoreCollection 定义 Microsoft 商家中心内的商店集合。
StoreCreate 定义要添加到 Microsoft 商家中心的商店。
StoreStatus 定义存储的状态。

错误

定义错误。

名称 值 类型
code 请求失败的原因。 例如，如果字段验证失败， storeName 则代码为 InvalidStoreNameErr。 String
消息 错误说明。 String

ErrorResponse

定义顶级错误对象。

名称 值 类型
错误 处理请求时发生的错误的列表。 Error[]

应用商店

在 Microsoft 商家中心定义商店。

名称 值 类型
isBlockAggregator 一个布尔值，指示是否要阻止聚合器从你的商店提供任何广告。 聚合器整合了来自多个（通常不相关的）企业的产品/服务。 默认情况下，聚合器可以在其广告中包含目录。

如果要防止产品显示在必应上的聚合器广告中，则 为 true 。 如果有两个存储 (一个用于美国，一个存储用于使用的http://www.contoso.com英国) ，其中一个存储块聚合器，则两个存储块聚合器。		 布尔值
isSslCheckout 一个布尔值，指示存储是否已启用 SSL。 所有商店都必须具有 SSL 登录和签出页。 如果商店的网站已启用 SSL，则为 true 。 布尔值
merchantId 存储的 ID。 无符号 long
notificationEmail 接收通知电子邮件的收件人列表。 当应用商店获得批准或存储存在验证错误时，电子邮件会通知你。 String[]
notificationLanguage 用于编写通知电子邮件的语言。 语言采用语言<>-国家/地区>的形式<。 例如，en-US。 String
storeDescription 描述存储使用情况的说明。 String
storeName 存储的名称。 String
storeStatus 存储的状态。 StoreStatus
storeUrl 存储的目标 URL。 目标 URL 是用户在单击广告时被定向到的网页。 String

StoreCollection

定义存储的列表。

名称 值 类型
商店 用户拥有的存储的列表。 Store[]

StoreCreate

定义要添加到 Microsoft 商家中心的商店。

名称 值 类型 必需
isBlockAggregator 一个布尔值，指示是否要阻止聚合器从你的商店提供任何广告。 聚合器整合了来自多个（通常不相关的）企业的产品/服务。 默认情况下，聚合器可以在其广告中包含目录。

设置为 true 可防止产品显示在必应上的聚合器广告中。 如果有两个存储 (一个用于美国，一个存储用于使用的http://www.contoso.com英国) ，其中一个存储块聚合器，则两个存储块聚合器。

默认值为 false。		 Boolean 否
isSslCheckout 一个布尔值，指示存储是否已启用 SSL。 所有商店都必须具有 SSL 登录和签出页。 如果商店的网站已启用 SSL，则设置为 true 。 如果 为 false ，则不批准存储。

默认值为 true。		 Boolean 否
notificationEmail 接收通知电子邮件的收件人列表。 当应用商店获得批准或存储存在验证错误时，电子邮件会通知你。 可以指定的电子邮件地址的最大数目为 14。 String[] 是
notificationLanguage 用于编写通知电子邮件的语言。 语言采用语言<>-国家/地区>的形式<。 以下是可以指定的可能不区分大小写的值。
  • en-US (english-美国)
  • en-AU (English-Australia)
  • en-GB (英语-英国)
  • fr-FR (法国-法国)
  • de-DE (德语-德国)
  • ja-JP (日日)
字符串 是
storeDescription 描述存储使用情况的说明。 说明最多只能包含 350 个字符，并且只能包含 ([a-zA-Z0-9]) 的字母数字字符。 字符串 否
storeName 存储的名称。 由于商店的名称显示在产品广告中，因此请务必使用准确表示您的网站的名称。 名称必须：
  • 在必应商家中心内独一无二
  • 包含不超过 70 个字符
  • 仅包含字母数字字符 ([a-zA-Z0-9])
字符串 是
storeUrl 存储的目标 URL。 目标 URL 是用户在单击广告时被定向到的网页。 URL 不能重定向到其他位置。 URL 的格式必须正确，最多包含 1,024 个字符。 必须 验证并声明网站的 URL。 如果 Microsoft 无法验证您的网站是否符合 SSL，则应用商店将不批准。 商家网站必须具有 SSL 登录和结帐页面。 验证 SSL 证书是否有效。 字符串 是

StoreStatus

定义存储的状态。

名称 值 类型
消息 商店被拒批的原因。 仅当 为“已批准”时 status ，对象才包括此字段。 String
status 存储的状态。 下面是可能的值。
  • 已批准
  • 反对
  • ManualReview
如果应用商店被拒登，请参阅 message 了解原因。

最初自动批准的存储区可以从“已批准”移动到 ManualReview。 不能将产品添加到正在手动审核的商店，并且商店中的产品将无法提供。

根据不批准的原因，你可以使用 Microsoft Ads 应用程序来解决此问题。 否则，需要创建具有适当值的新存储区。		 String

HTTP 状态代码

请求可能会返回以下 HTTP 状态代码。

状态代码 说明
200 成功。
201 已成功添加存储。
400 错误请求。 很可能 POST 请求的正文包含无效数据或格式不正确。
401 未经授权。 用户的凭据无效。
404 未找到。 找不到请求的存储。
500 服务器错误。

错误代码

请求可能会返回以下错误代码。

错误代码 说明
AdultAdvertiserErr 成人广告客户不得创建商店。
DomainNotOwnedByCustomerErr storeUrl 字段中指定的域不归客户所有。 确保客户已验证他们拥有该域。
DuplicateStoreNameErr 存在具有指定存储名称的另一个存储区;Microsoft 商家中心必须具有唯一的商店名称。
ExceededMaxStoresForCustomerErr 客户超出了他们可以创建的商店数量。 有关限制，请参阅 添加存储 POST。
ExceededMaxStoresForDestinationUrlErr 客户超出了他们可以使用同一目标 URL 创建的商店数量。 有关限制，请参阅 添加存储 POST。
InvalidStoreDescriptionErr 存储区的说明无效。 有关限制，请参阅 storeDescription。
InvalidStoreDestinationUrlErr 在 storeUrl 字段中指定的应用商店的目标 URL 无效。
InvalidStoreNameErr 存储区的名称无效。 有关限制，请参阅 storeName。
MarketNotSupportedErr 在 notificationLanguage 字段中指定的市场无效。
NoDomainsFoundForCustomerErr 客户没有经过验证的域。