Regions

regions 服务可让您创建和管理地理区域，以便您将这些区域用作 regionalinventory 和 shippingsettings 服务的目标。您可以将区域定义为邮政编码集合，或者在 某些国家/地区，使用预定义 地理位置定位条件。本指南提供了有关如何定义每种类型的区域以及如何创建区域价格替换的示例。如需详细了解 regions 服务（包括所有可用方法和参数），请参阅参考文档。

注意 ：每个区域定义只能包含邮政编码或 地理位置定位条件，而不能同时包含两者。

区域资格

创建区域时，区域服务会确定您是否可以将该区域与其他 Content API 服务搭配使用。对于成功的 regions.create 调用，返回的响应对象包含两个布尔值字段：regionalInventoryEligible 和 shippingEligible，分别表示您是否可以将该区域与 regionalinventory 和 shippingsettings 服务搭配使用。

regionalInventoryEligible

如需有资格与 regionalinventory 服务搭配使用，区域必须满足以下条件：

• 您在创建区域时指定的 regionId 必须仅包含数字，并且必须包含至少 2 位数字。
• 该区域必须满足地理区域和在线人口的最低规模要求。

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*"
      }
    ]
   }
}

注意： 如果您收到“quota/too_many_regions”错误，则表示您的账号中用于存储区域的空间已用完。

每个 Merchant Center 账号的 regions 和 shippingsettings 的数据硬性限制为 2MB。送货和区域设置会在内部从 MCA 复制到其所有子账号，因此对于较大的 MCA，您可能会很快达到存储空间限制。在这种情况下，一种解决方法是在商家 ID 级别管理 regions 和 shippingsettings。您无法将区域配额增加到超过 2MB 的限制。

使用地理位置定位条件创建区域

对于巴西和俄罗斯的区域，您还可以使用 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 和两个 资格 状态字段。如果 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'
}