迁移区域管理

本指南介绍了如何将集成从 Content API for Shopping 中的 RegionsService 迁移到 Accounts 子 API 中的 RegionsService。

借助“地区”服务，您可以定义自定义地理区域，以用于区域性价格和配送替换等使用情形。您可以将区域与 RegionalInventory 和 ShippingSettings 等服务搭配使用。

主要差异

• API 结构：Regions 服务现在是 Merchant API 中 Accounts 子 API 的一部分（例如，merchantapi.googleapis.com/accounts/v1/...）。
• 资源名称：Merchant API 使用资源名称 (accounts/{account}/regions/{region}) 而不是单独的 merchant_id 和 region_id 参数（位于网址路径中）来执行 Get、Update 和 Delete 操作。
• AIP 合规性：Merchant API 方法遵循标准 API 改进提案模式（例如，使用 parent 表示 List/Create，使用 name 表示 Get/Delete，以及标准 update_mask 用法）。
• 封装容器类型：之前在 Content API 中使用 google.protobuf.StringValue 或 google.protobuf.BoolValue 的字段现在在 Merchant API 中使用标准 optional 字段。
• 新功能：
  • Merchant API 在 Region 资源中引入了 RadiusArea 类型，用于根据某个点周围的半径定义区域（最初具有 TRUST_TESTER 可见性）。
  • 批处理方法（BatchCreateRegions、BatchUpdateRegions、BatchDeleteRegions）现已推出。
• 错误处理：错误代码和消息可提供更具体的反馈。

请求

以下是请求模式的变化：

商品	Content API for Shopping	Merchant API	说明
端点	https://shoppingcontent.googleapis.com	https://merchantapi.googleapis.com	基本网域发生变化。
获取路径	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Merchant API 使用 accounts 子 API 和资源 name。
列出路径	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	Merchant API 使用 parent 指定账号。
创建路线	/content/v2.1/{merchant_id}/regions	/accounts/v1/{parent=accounts/*}/regions	Merchant API 使用 parent。region_id 是请求正文中的一个字段。
更新路径	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	Merchant API 中的资源名称是正文中 region 对象的一部分。
删除路径	/content/v2.1/{merchant_id}/regions/{region_id}	/accounts/v1/{name=accounts/*/regions/*}	使用资源 name。

标识符

请按如下方式更改标识符的使用方式：

商品	Content API for Shopping	Merchant API	说明
账号	merchant_id（整数）	account（整数，name 或 parent 字符串的一部分）	找到嵌入在资源名称字符串中的账号 ID，例如 accounts/{account}。
区域	region_id（字符串）	{region}（字符串，name 字符串的一部分）	找到嵌入在资源名称字符串中的地区 ID，例如 accounts/{account}/regions/{region}。
资源名称	不严格用于请求。	name：accounts/{account}/regions/{region}	Get/Update/Delete 请求的标准标识符。
家长姓名	不严格用于请求。	parent：accounts/{account}	List/Create 请求的标准标识符。

资源

Region 资源结构发生了细微变化：

商品	Content API for Shopping	Merchant API	说明
资源标识符	region_id（字符串），merchant_id（int64）	name（字符串）：accounts/{account}/regions/{region}	Merchant API 使用单个 name 字段作为资源标识符。
display_name	google.protobuf.StringValue	optional string	移除了封装容器类型。
radius_area	不适用 (N/A)	RadiusArea	这种新类型按半径定义区域。包括 region_code、lat_lng、radius、radius_units。默认情况下，公开范围受到限制。
regional_inventory_eligible	google.protobuf.BoolValue（仅限输出）	optional bool（仅限输出）	移除了封装容器类型。
shipping_eligible	google.protobuf.BoolValue（仅限输出）	optional bool（仅限输出）	移除了封装容器类型。

方法

按如下方式更改方法的使用：

商品	Content API for Shopping	Merchant API	说明
获取区域	GetRegion	GetRegion	该请求使用 name。
创建地区	CreateRegion	CreateRegion	请求从网址中获取 parent，而请求正文包含 region 对象和 region_id。
更新区域	UpdateRegion	UpdateRegion	该请求使用 region（必须包含 region.name）和 update_mask。
删除区域	DeleteRegion	DeleteRegion	相应请求使用 name。
列出地区	ListRegions	ListRegions	该请求使用 parent。page_size 和 page_token 行为保持一致。
批量创建	不适用	BatchCreateRegions	这是一种新方法。
批量更新	不适用	BatchUpdateRegions	这是一种新方法。
批量删除	不适用	BatchDeleteRegions	这是一种新方法。

重命名的字段

商品	Content API for Shopping	Merchant API	说明
账号 ID	merchant_id	account（属于 name 或 parent）	集成到资源 name 字符串中。这会影响 Region（响应）和用于发出 API 请求的 protobuf 消息，例如 CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest 和 ListRegionsRequest。
地区 ID	region_id	region（name 的一部分），region_id	集成到 name 中（适用于大多数情况），在 CreateRegionRequest 中单独使用 region_id 字段。这会影响 Region（响应）和用于发出 API 请求的 protobuf 消息，例如 CreateRegionRequest, GetRegionRequest, UpdateRegionRequest, DeleteRegionRequest 和 ListRegionsRequest。
地区名称（输出）	region_id	name	响应中的主要标识符字段现在是完整的资源 name。这会影响 Region。
显示名称	display_name	display_name	类型从 StringValue 更改为 optional string。 这会影响 Region。
资格标志	...eligible	...eligible	类型从 BoolValue 更改为 optional bool。 这会影响 Region。
更新掩码	update_mask	update_mask	Region 个字段路径。这会影响 UpdateRegionRequest。

了解详情

• Merchant API 的 REST 资源：accounts.regions
• 地区指南
• 设置地区