本頁面由 Cloud Translation API 翻譯而成。

區域

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”
}