遷移區域管理

本指南說明如何將整合項目從 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})，而非在網址路徑中，為 Get、Update 和 Delete 作業使用獨立的 merchant_id 和 region_id 參數。
符合 AIP 規範：Merchant API 方法遵循標準 API 改進提案模式 (例如使用 parent 進行清單/建立、name 進行取得/刪除，以及標準 update_mask 用法)。
包裝函式類型：在 Content API 中，先前使用 google.protobuf.StringValue 或 google.protobuf.BoolValue 的欄位，現在在 Merchant API 中使用標準 optional 欄位。
新功能：
- Merchant API 在 Region 資源中導入 RadiusArea 類型，根據某個點周圍的半徑定義區域 (一開始為 TRUST_TESTER 顯示設定)。
- 可使用批次方法：BatchCreateRegions、BatchUpdateRegions、BatchDeleteRegions。
錯誤處理：錯誤代碼和訊息可提供更具體的回饋。

要求模式的變更方式如下：

Item	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`。

請按照下列方式變更 ID 的使用方式：

Item	Content API for Shopping	Merchant API	說明
帳戶	`merchant_id` (整數)	`account` (整數，`name` 或 `parent` 字串的一部分)	找出嵌入資源名稱字串中的帳戶 ID，例如 `accounts/{account}`。
Region	`region_id` (字串)	`{region}` (字串，`name` 字串的一部分)	找出內嵌在資源名稱字串中的區域 ID，例如 `accounts/{account}/regions/{region}`。
資源名稱	不限於要求。	`name`：`accounts/{account}/regions/{region}`	Get/Update/Delete 要求的標準 ID。
Parent Name	不限於要求。	`parent`：`accounts/{account}`	List/Create 要求的標準 ID。

Region 資源結構有微幅異動：

Item	Content API for Shopping	Merchant API	說明
資源 ID	`region_id` (字串)、`merchant_id` (int64)	`name` (字串)：`accounts/{account}/regions/{region}`	Merchant API 使用單一 `name` 欄位做為資源 ID。
`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` (僅限輸出)	已移除包裝函式類型。

請按照下列方式變更方法：

Item	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`	這是新方法。

Item	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`	回應中的主要 ID 欄位現在是完整資源 `name`。這會影響 `Region`。
顯示名稱	`display_name`	`display_name`	類型從 `StringValue` 變更為 `optional string`。這會影響 `Region`。
資格標記	`...eligible`	`...eligible`	類型從 `BoolValue` 變更為 `optional bool`。這會影響 `Region`。
更新遮罩	`update_mask`	`update_mask`	`Region` 個欄位路徑。這會影響 `UpdateRegionRequest`。