Package google.shopping.merchant.promotions.v1beta

索引

• PromotionsService（接口）
• Attributes（消息）
• CouponValueType（枚举）
• GetPromotionRequest（消息）
• InsertPromotionRequest（消息）
• ListPromotionsRequest（消息）
• ListPromotionsResponse（消息）
• OfferType（枚举）
• ProductApplicability（枚举）
• Promotion（消息）
• PromotionStatus（消息）
• PromotionStatus.DestinationStatus（消息）
• PromotionStatus.DestinationStatus.State（枚举）
• PromotionStatus.ItemLevelIssue（消息）
• PromotionStatus.ItemLevelIssue.Severity（枚举）
• RedemptionChannel（枚举）
• StoreApplicability（枚举）

PromotionsService

用于管理商品促销活动的服务。

GetPromotion
rpc GetPromotion(GetPromotionRequest) returns (Promotion) 从您的 Merchant Center 帐号中检索促销活动。 插入或更新促销活动输入内容后，系统可能需要几分钟时间才能检索到更新后的促销活动。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/content 如需了解详情，请参阅 OAuth 2.0 概览。

InsertPromotion
rpc InsertPromotion(InsertPromotionRequest) returns (Promotion) 为您的 Merchant Center 帐号插入促销活动。如果促销活动已存在，则系统会改为更新该促销活动。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/content 如需了解详情，请参阅 OAuth 2.0 概览。

ListPromotions
rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse) 列出您的 Merchant Center 帐号中的促销活动。响应包含的项数可能少于 pageSize 指定的项。依靠 pageToken 来确定是否还要请求更多内容。 插入或更新促销活动后，可能需要过几分钟才能检索到更新后的已处理促销活动。 授权范围 需要以下 OAuth 范围： https://www.googleapis.com/auth/content 如需了解详情，请参阅 OAuth 2.0 概览。

属性

属性。

字段
product_applicability	ProductApplicability 必需。促销活动是否适用于所有商品或仅适用于指定商品。
offer_type	OfferType 必需。促销活动的类型。使用此属性可指明客户是否需要优惠券代码来兑换您的促销优惠。
generic_redemption_code	string 可选。促销活动的通用兑换码。要与 offerType 字段搭配使用，且必须满足最低要求。
long_title	string 必需。促销活动的长标题。
coupon_value_type	CouponValueType 必需。coupon value type 属性，用于指明您开展的促销活动的类型。根据所选优惠券值的类型，某些属性是必需属性。
promotion_destinations[]	DestinationEnum 必需。促销活动适用的目标平台的列表。如果您未通过在数据源中添加受支持的值来指定目标平台，则默认情况下，您的促销活动将在购物广告和非付费商品详情中展示。 您以前可能提交了以下值作为商品展示平台：购物行动计划、Google 跨平台呈现、本地 Google 平台呈现。如需表示这些值，请使用 FREE_LISTINGS、FREE_LOCAL_LISTINGS 和 LOCAL_INVENTORY_ADS。如需了解详情，请参阅促销平台
item_id_inclusion[]	string 可选。按促销活动的 item ID 过滤商品。仅当符合促销条件的商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
brand_inclusion[]	string 可选。按品牌过滤促销活动的商品。仅当符合促销条件的商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
item_group_id_inclusion[]	string 可选。按促销活动的商品组 ID 过滤商品。仅当“符合促销条件的商品”[product_applicability] 属性设置为 specific_products 时，商品过滤条件属性才适用。
product_type_inclusion[]	string 可选。按促销活动的商品类型过滤商品。仅当符合促销条件的商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
item_id_exclusion[]	string 可选。按促销活动的商品 ID 排除过滤商品。仅当符合促销条件的商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
brand_exclusion[]	string 可选。按促销活动的品牌排除过滤商品。仅当符合促销条件的商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
item_group_id_exclusion[]	string 可选。按 item group ID 过滤商品。仅当符合促销条件的商品的适用商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
product_type_exclusion[]	string 可选。按促销活动的产品类型排除过滤产品。仅当符合促销条件的商品 product_applicability 属性设置为 specific_products 时，商品过滤条件属性才适用。
minimum_purchase_amount	Price 可选。促销活动的最低交易额。
minimum_purchase_quantity	int64 可选。促销活动的最低购买数量。
limit_quantity	int64 可选。促销活动的购买数量上限。
limit_value	Price 可选。促销活动的最高商品价格。
percent_off	int64 可选。促销活动中提供的百分比折扣。
money_off_amount	Price 可选。促销活动中提供的折扣金额。
get_this_quantity_discounted	int64 可选。促销活动中打折的商品数量。当 couponValueType 等于 buy_m_get_n_money_off 或 buy_m_get_n_percent_off 时，系统会设置此属性。
free_gift_value	Price 可选。促销活动的赠品价值。
free_gift_description	string 可选。促销活动的赠品说明。
free_gift_item_id	string 可选。促销活动的赠品商品 ID。
promotion_effective_time_period	Interval 必需。TimePeriod，表示促销活动的生效日期。此属性指定在此期间可以在您的网店中测试促销活动。
promotion_display_time_period	Interval 可选。TimePeriod 表示促销活动展示日期。此属性用于指定在 Google.com 和购物广告上投放促销活动的日期和时间范围。如果未指定促销展示时间段 promotion_display_time_period 属性，则促销活动有效期 promotion_effective_time_period 将决定在 Google.com 和购物广告上投放促销活动的日期和时间范围。
store_applicability	StoreApplicability 可选。促销活动适用于所有商店，还是仅适用于指定的商店。如果没有添加商店适用性信息，本地产品目录广告促销活动会抛出错误。如果 store_applicability 设置为 ALL_STORES 且 store_codes_inclusion 或 score_code_exclusion 设置为一个值，则会抛出 INVALID_ARGUMENT 错误。
store_codes_inclusion[]	string 可选。要为促销活动添加的商店代码。商店过滤条件属性仅在 store_applicability 属性设置为 specific_stores 时适用。 销售商品的实体店的商店代码（即您的商家资料中的商店 ID）。如需了解详情，请参阅本地商品目录数据规范。
store_codes_exclusion[]	string 可选。要为促销活动排除的商店代码。商店过滤条件属性仅在 store_applicability 属性设置为 specific_stores 时适用。
promotion_url	string 可选。指向商家网站上显示促销活动的网页的网址。如果未添加 promotion_url，本地产品目录广告促销活动会抛出错误。网址用于确认促销活动有效且可以兑换。

CouponValueType

促销活动的优惠券价值类型。

枚举
COUPON_VALUE_TYPE_UNSPECIFIED	表示未指定优惠券值类型。
MONEY_OFF	折扣优惠券价值类型。
PERCENT_OFF	折扣优惠券价值类型。
BUY_M_GET_N_MONEY_OFF	优惠券价值类型是买 M 件，立减 N 笔。必须存在 minimum_purchase_quantity 和 get_this_quantity_discounted。money_off_amount。
BUY_M_GET_N_PERCENT_OFF	购买 M 件，立减 N% 的优惠券价值类型。必须存在 minimum_purchase_quantity 和 get_this_quantity_discounted。percent_off_percentage。
BUY_M_GET_MONEY_OFF	购 M 件，享优惠。必须有 minimum_purchase_quantity 和 money_off_amount。
BUY_M_GET_PERCENT_OFF	购 M 件，享优惠。必须有 minimum_purchase_quantity 和 percent_off_percentage。
FREE_GIFT	仅含说明的赠品。
FREE_GIFT_WITH_VALUE	具有货币价值的赠品。
FREE_GIFT_WITH_ITEM_ID	带有商品 ID 的赠品。
FREE_SHIPPING_STANDARD	标准免运费优惠券值类型。
FREE_SHIPPING_OVERNIGHT	次日免运费优惠券值类型。
FREE_SHIPPING_TWO_DAY	两日免费配送优惠券值类型。

GetPromotionRequest

对 GetPromotion 方法的请求消息。

字段
name	string 必需。要检索的促销活动的名称。格式：accounts/{account}/promotions/{promotions}

InsertPromotionRequest

对 InsertPromotion 方法的请求消息。

字段
parent	string 必需。将在其中插入促销活动的账号。格式：accounts/{account}
promotion	Promotion 必需。要插入的促销信息。
data_source	string 必需。推广活动的数据源，格式为：accounts/{account}/dataSources/{datasource}。

ListPromotionsRequest

对 ListPromotions 方法的请求消息。

字段
parent	string 必需。要为其列出已处理的促销信息的账号。格式：accounts/{account}
page_size	int32 仅限输出。要返回的促销活动数量上限。服务返回的值可能小于此值。最大值为 1000；大于 1000 的值将被强制转换为 1000。如果未指定，将返回促销数量上限。
page_token	string 仅限输出。从之前的 ListPromotions 调用接收的页面令牌。利用其进行后续页面检索。 进行分页时，提供给 ListPromotions 的所有其他参数必须与提供页面令牌的调用匹配。

ListPromotionsResponse

ListPromotions 方法的响应消息。

字段
promotions[]	Promotion 指定账号中已处理的促销信息。
next_page_token	string 可作为 page_token 发送并用于检索下一页的令牌。如果省略此字段，则不存在后续页面。

OfferType

促销活动的优惠类型。

枚举
OFFER_TYPE_UNSPECIFIED	未知优惠类型。
NO_CODE	不含代码的优惠类型。
GENERIC_CODE	包含代码的优惠类型。当 offerType = GENERIC_CODE 时，必须提供促销活动的通用兑换码。

ProductApplicability

促销活动适用的商品或商品列表。

枚举
PRODUCT_APPLICABILITY_UNSPECIFIED	未知促销活动适用于哪些商品。
ALL_PRODUCTS	适用于所有商品。
SPECIFIC_PRODUCTS	仅适用于单件商品或商品列表。

推广

表示促销活动。如需了解详情，请参阅以下文章。

为了通过数据验证检查，必须填写的促销输入属性主要定义如下：

• 促销数据规范
• 本地促销数据规范

插入并更新促销活动输入内容后，系统可能需要几分钟时间才能检索到最终的促销活动。

字段
name	string 标识符。促销活动的名称。格式：accounts/{account}/promotions/{promotion}
promotion_id	string 必需。用户提供的促销 ID，用于唯一标识相应促销活动。遵循最低要求，防止促销活动遭到拒批。
content_language	string 必需。促销活动的双字母 ISO 639-1 语言代码。 促销活动仅适用于部分语言。
target_country	string 必需。用作唯一标识符一部分的目标国家/地区。以 CLDR 地区代码表示。 促销活动仅在部分国家/地区提供，非付费商品详情和购物广告 本地产品目录广告
redemption_channel[]	RedemptionChannel 必需。促销活动的兑换渠道。至少需要一个渠道。
data_source	string 仅限输出。促销活动的主要数据源。
attributes	Attributes 可选。促销活动属性列表。
custom_attributes[]	CustomAttribute 可选。自定义（商家提供的）属性列表。它还可用于以通用形式提交数据规范中的任何属性（例如，{ "name": "size type", "value": "regular" }）。这对于提交 API 未明确提供的属性非常有用。
promotion_status	PromotionStatus 仅限输出。促销活动的状态、数据验证问题，即异步计算的促销活动的相关信息。
version_number	int64 可选。表示促销活动的现有版本（新鲜度），可用于在同时进行多项更新时保持正确的顺序。 设置后，当版本号低于现有促销活动的当前版本号时，系统会阻止插入。您可以使用当前的 version_number 重新插入（例如，在 30 天后刷新促销活动）。 如果操作被阻止，则会抛出已中止的异常。

PromotionStatus

促销活动的状态。

字段
destination_statuses[]	DestinationStatus 仅限输出。促销活动的目标平台。
item_level_issues[]	ItemLevelIssue 仅限输出。与促销活动相关的问题列表。
creation_date	Timestamp 仅限输出。促销活动的创建日期（采用 ISO 8601 格式）：日期、时间和偏移值，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z
last_update_date	Timestamp 仅限输出。促销状态的上次更新日期（ISO 8601 格式）：日期、时间和偏移值，例如 2020-01-02T09:00:00+01:00 或 2020-01-02T09:00:00Z

DestinationStatus

指定目标的状态。

字段
reporting_context	ReportingContextEnum 仅限输出。促销平台的名称。
status	State 仅限输出。指定目标的状态。

状态

促销活动的当前状态。

枚举
STATE_UNSPECIFIED	促销活动状态未知。
IN_REVIEW	促销活动正在审核中。
REJECTED	促销活动未获批准。
LIVE	促销活动已获批准并处于有效状态。
STOPPED	商家停止了促销活动。
EXPIRED	促销活动已失效。
PENDING	促销活动并未停止，并且所有审核都已获得批准，但生效日期是未来的日期。

ItemLevelIssue

与促销活动相关的问题。

字段
code	string 仅限输出。问题的错误代码。
severity	Severity 仅限输出。此问题对促销活动的投放有何影响。
resolution	string 仅限输出。商家能否解决问题。
attribute	string 仅限输出。属性的名称（如果问题是由单个属性导致的）。
reporting_context	ReportingContextEnum 仅限输出。问题适用的目标位置。
description	string 仅限输出。英文的简短问题说明。
detail	string 仅限输出。详细的问题说明（英文）。
documentation	string 仅限输出。帮助解决此问题的网页的网址。
applicable_countries[]	string 仅限输出。商品存在问题的国家/地区代码列表 (ISO 3166-1 alpha-2)。

严重级别

问题的严重程度。

枚举
SEVERITY_UNSPECIFIED	未指定。
NOT_IMPACTED	此问题只是一个警告，不会对促销活动产生直接影响。
DEMOTED	相应促销活动已降位，在搜索结果中的效果很可能会受到限制
DISAPPROVED	问题拒批了促销活动。

RedemptionChannel

推广活动的渠道。

枚举
REDEMPTION_CHANNEL_UNSPECIFIED	表示未指定渠道。
IN_STORE	表示频道在商店内。这与用于 products 的 local 频道相同。
ONLINE	表示频道处于在线状态。

StoreApplicability

促销代码或促销活动适用的商店代码列表。仅适用于本地商品目录广告促销活动。

枚举
STORE_APPLICABILITY_UNSPECIFIED	促销优惠适用于哪些商店代码。
ALL_STORES	促销适用于所有商店。
SPECIFIC_STORES	促销活动仅适用于指定的商店。