遷移區域管理

本指南說明如何將整合程序從 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 參數。
API 改進提案 (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。
錯誤處理：錯誤代碼和訊息可提供更具體的意見回饋。

以下是請求模式的變化：

項目	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 的使用方式：

項目	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 要求的標準 ID。
家長姓名	不嚴格用於要求。	`parent`：`accounts/{account}`	List/Create 要求的標準 ID。

Region 資源結構有小幅變動：

項目	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` (僅限輸出)	已移除包裝器類型。

請依下列方式變更方法的使用方式：

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