regions
服務可讓您建立及管理地理區域,並能做為 regionalinventory
和 shippingsettings
服務的目標使用。您可以將區域定義為郵遞區號的集合,在某些國家/地區,使用預先定義的指定地理區域。本指南提供範例,說明如何定義各個區域類型,以及如何建立區域價格覆寫。如要進一步瞭解 regions
服務,包括所有可用方法和參數,請參閱參考說明文件。
區域資格條件
建立區域時,區域服務會決定該區域是否能與其他 Content API 服務搭配使用。成功的 regions.create
呼叫傳回的回應物件包含兩個布林欄位 (regionalInventoryEligible
和 shippingEligible
),指出您是否能將該區域與 regionalinventory
和 shippingsettings
服務分別搭配使用。
regionalInventoryEligible
如要符合 regionalinventory
服務的使用資格,區域必須符合下列條件:
- 建立區域時指定的
regionId
,只能包含數字,且至少必須包含 6 位數字。 - 區域必須符合地理區域和線上填入的最低大小要求。
shippingEligible
如要符合 shippingsettings
服務的使用資格,區域必須符合下列條件:
- 請使用郵遞區號定義區域。
- 區域必須位於
shippingsettings
服務支援的國家/地區內。
範例
以下是您可以在 Java 中建立新區域的完整程式碼範例:
// Copyright 2023 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package shopping.content.v2_1.samples.regions; import com.google.api.client.googleapis.json.GoogleJsonResponseException; import com.google.api.services.content.model.Region; import com.google.api.services.content.model.RegionPostalCodeArea; import com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange; import java.io.IOException; import java.util.ArrayList; import java.util.List; import shopping.content.v2_1.samples.ContentSample; /** * Creates a region. The region created here can be used with the regional inventory service. * Regional availability and pricing lets you provide product availability and variable pricing * based on your business presence and the location of your customer base. Regional availability and * pricing is available for products advertised through Shopping ads on Google Search, and listed in * free listings on the Shopping tab. */ public class RegionCreateSample extends ContentSample { public RegionCreateSample(String[] args) throws IOException { super(args); } @Override public void execute() throws IOException { checkNonMCA(); // Creates a List of Postal Code Area Postal Code Ranges. // This allows you to flexibly define regions as combinations of postal code // ranges. Each postal code range in the list has its own start and end zip code. List<RegionPostalCodeAreaPostalCodeRange> postalCodeRanges = new ArrayList<RegionPostalCodeAreaPostalCodeRange>(); // Creates a new postal code range from two postal code values. // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925) RegionPostalCodeAreaPostalCodeRange postalCodeRange = new RegionPostalCodeAreaPostalCodeRange().setBegin("00501").setEnd("14925"); // Adds the NY State postal code range into the list of postal code ranges that a postal // code area accepts. postalCodeRanges.add(postalCodeRange); // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code // ranges, and the US CLDR territory/country code that the postal code ranges applies to. RegionPostalCodeArea postalCodeArea = new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode("US"); // Creates a region with example values for displayName and postalCodeArea Region region = new Region().setDisplayName("NYState").setPostalCodeArea(postalCodeArea); // Tries to create the region, and catches any exceptions try { System.out.println("Creating region"); Region result = content .regions() .create(this.config.getMerchantId().longValue(), region) .setRegionId("12345678") // User-defined, numeric, minimum of 6 digits .execute(); System.out.println("Listing succesfully created region"); System.out.println(result); } catch (GoogleJsonResponseException e) { checkGoogleJsonResponseException(e); } } public static void main(String[] args) throws IOException { new RegionCreateSample(args).execute(); } }
使用郵遞區號建立區域
您可以使用 regions.create
方法,建立一個定義為郵遞區號集合的區域。以下範例透過指定郵遞區號範圍的方式,為美國亞利桑那州建立新的區域。
如要建立區域,請使用以下網址發出 POST
要求,並要求主體:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789
{
postalCodeArea: {
regionCode: "US",
postalCodes: [
{
begin: "850*",
end: "860*"
}
]
}
}
每個 Merchant Center 帳戶的 regions
和 shippingsettings
資料最多只能有 2 MB 的資料。運送與地區設定會在內部從 MCA 複製到其所有子帳戶,因此大型 MCA 可能快速達到儲存空間上限。在這種情況下,其中一種解決方法是在商家 ID 層級管理 regions
和 shippingsettings
。您無法提高超過 2 MB 的區域配額。
使用指定地理區域建立區域
對於巴西和俄羅斯的區域,您也可以使用 regions.create
方法,建立一個定義為指定地理區域集合的區域,這些是預先定義的地理區域。指定地理區域類型範例包括國家/地區、州/省、城市、社區和機場。不過,regions
服務目前僅支援巴西的「州/省」類型,以及俄羅斯的「區域」類型。如要下載包含所有指定地理區域 ID 的 CSV 檔案 (包括可與 regions
服務搭配使用的指定地理區域),請參閱「指定地理區域」一文。下例是提供三個巴西州的指定地理區域 ID,藉此建立新的區域。
如要建立區域,請使用以下網址發出 POST
要求並要求主體:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456
{
geoTargetAreas: {
geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
}
}
使用區域來建立區域價格覆寫設定
建立區域時,regions
服務會傳回回應物件,其中包含 regionId
和兩個「eligibility」狀態欄位。如果 regionalInventoryEligible
值為 true
,您可以使用 regionaliventory
服務建立覆寫值,為該區域設定不同的價格。以下範例使用在上述範例中建立的郵遞區號區域 (regionId
為「456789」),建立區域價格覆寫值。
如要建立覆寫值,請使用以下網址和要求主體發出 POST
要求:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory
{
“regionId”: "456789"
“price”: {
value: “10”
currency: “USD”
},
“availability”: “in stock”
}