Regiony

Usługa regions umożliwia tworzenie regionów geograficznych i zarządzanie nimi, których możesz używać jako miejsc docelowych w usługach regionalinventory i shippingsettings. Regiony możesz definiować jako zbiory kodów pocztowych lub, w niektórych krajach, za pomocą wstępnie zdefiniowanych geotargetów. W tym przewodniku znajdziesz przykłady definiowania każdego typu regionu oraz tworzenia zastąpienia ceny regionalnej. Więcej informacji o usłudze regions, w tym o wszystkich dostępnych metodach i parametrach, znajdziesz w dokumentacji.

Kwalifikowanie się regionu

Gdy tworzysz region, usługa regions sprawdza, czy możesz go używać w innych usługach Content API. Obiekt odpowiedzi zwracany w przypadku udanego wywołania regions.create zawiera 2 pola logiczne: regionalInventoryEligible i shippingEligible. Wskazują one, czy możesz używać regionu odpowiednio w usługach regionalinventory i shippingsettings.

regionalInventoryEligible

Aby region kwalifikował się do użycia w usłudze regionalinventory, musi spełniać te kryteria:

  • Wartość regionId podana podczas tworzenia regionu musi zawierać tylko cyfry i co najmniej 2 cyfry.
  • Region musi spełniać minimalne wymagania dotyczące wielkości obszaru geograficznego i populacji online.

shippingEligible

Aby region kwalifikował się do użycia w usłudze shippingsettings, musi spełniać te kryteria:

  • Region musi być zdefiniowany za pomocą kodów pocztowych.
  • Region musi znajdować się w kraju obsługiwanym przez usługę shippingsettings.

Przykłady

Oto pełny przykład kodu, którego możesz użyć do utworzenia nowego regionu w Javie:

// 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();
  }
}

Tworzenie regionu za pomocą kodów pocztowych

Za pomocą regions.create metody możesz utworzyć region zdefiniowany jako zbiór kodów pocztowych. Poniższy przykład tworzy nowy region dla stanu Arizona w Stanach Zjednoczonych, określając zakres kodów pocztowych.

Aby utworzyć region, wyślij żądanie POST z tym adresem URL i treścią żądania:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodeArea: {
    regionCode: "US",
    postalCodes: [
      {
        begin: "850*",
        end: "860*"
      }
    ]
   }
}

Na każdym koncie Merchant Center obowiązuje limit 2 MB danych dla usług regions i shippingsettings. Ustawienia dostawy i regionu są wewnętrznie kopiowane z konta zbiorczego na wszystkie jego konta podrzędne, dlatego w przypadku większych kont zbiorczych możesz szybko osiągnąć limit miejsca. W takim przypadku możesz zarządzać usługami regions i shippingsettings na poziomie identyfikatora sprzedawcy. Nie ma możliwości zwiększenia limitu regionów powyżej 2 MB.

Tworzenie regionu za pomocą geotargetów

W przypadku regionów w Brazylii i Rosji możesz też użyć metody regions.create, aby utworzyć region zdefiniowany jako zbiór geotargetów, czyli wstępnie zdefiniowanych obszarów geograficznych. Przykłady typów geotargetów to kraje, stany, miasta, dzielnice i lotniska. Usługa regions obsługuje jednak tylko typ „State” w Brazylii i typ „Region” w Rosji. Aby pobrać plik CSV ze wszystkimi identyfikatorami geotargetów, w tym geotargetami, których można używać w usłudze regions, zapoznaj się z artykułem Geotargety. Poniższy przykład tworzy nowy region, podając identyfikatory geotargetów 3 stanów w Brazylii.

Aby utworzyć region, wyślij żądanie POST z tym adresem URL i treścią żądania:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456

{
  geoTargetAreas: {
    geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
  }
}

Używanie regionów do tworzenia zastąpień cen regionalnych

Gdy tworzysz region, usługa regions zwraca obiekt odpowiedzi, który zawiera regionId i 2 pola stanu kwalifikowania się. Jeśli wartość regionalInventoryEligible to true, możesz użyć usługi regionaliventory, aby utworzyć zastąpienie, które ustawi inną cenę dla regionu. Poniższy przykład tworzy zastąpienie ceny regionalnej za pomocą regionu opartego na kodach pocztowych utworzonego w poprzednim przykładzie, który ma regionId o wartości „456789”.

Aby utworzyć zastąpienie, wyślij żądanie POST z tym adresem URL i treścią żądania:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory

{
  'regionId': "456789"
  'price': {
    value: '10'
    currency: 'USD'
  },
  'availability': 'in stock'
}