借助 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
的数据量硬性上限为 2MB。配送和地区设置会在内部从 MCA 复制到其所有子帐号,因此对于较大的 MCA,您可能会很快达到存储空间上限。在这种情况下,一种权宜解决方法是在商家 ID 级别管理 regions
和 shippingsettings
。您无法将区域配额增加到超过 2MB 的限制。
使用地理位置定位创建区域
对于巴西和俄罗斯的区域,您还可以使用 regions.create
方法创建一个区域,该区域定义为一系列地理位置定位,也就是预定义的地理区域。地理位置定位类型示例包括国家/地区、州/省/自治区/直辖市、城市、社区和机场。但是,regions
服务目前仅支持“州”类型(巴西)和“区域”类型(俄罗斯)。如需下载包含所有地理位置定位 ID(包括可与 regions
服务搭配使用的地理位置定位)的 csv 文件,请参阅地理位置定位。下例通过提供巴西三个州的地理位置定位 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
和两个资格状态字段的响应对象。如果 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”
}