Regiony

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

Wymagania dotyczące regionu

Gdy utworzysz region, usługa regionów określa, czy możesz go używać z innymi usługami Content API. Obiekt odpowiedzi zwrócony w przypadku udanego wywołania regions.create zawiera 2 pola wartości logicznej regionalInventoryEligible i shippingEligible, które wskazują, czy możesz używać tego regionu z usługami regionalinventory i shippingsettings.

regionalInventoryEligible

Aby móc używać usługi regionalinventory, region musi spełniać te kryteria:

  • regionId, który określasz podczas tworzenia regionu, może zawierać tylko cyfry i musi zawierać co najmniej 6 cyfr.
  • Region musi spełniać wymagania dotyczące wielkości obszaru geograficznego i liczby ludności online.

shippingEligible

Aby móc używać usługi shippingsettings, region musi spełniać te kryteria:

  • Region musi być zdefiniowany za pomocą kodów pocztowych.
  • Region musi należeć do kraju obsługiwanego przez usługę shippingsettings.

Sample

Oto pełny przykładowy kod, 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

Aby utworzyć region zdefiniowany jako zbiór kodów pocztowych, możesz użyć metody regions.create. W podanym niżej przykładzie tworzony jest nowy region stanu Arizona w USA przez określenie zakresu 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*"
      }
    ]
   }
}

W przypadku usług regions i shippingsettings na konto Merchant Center obowiązuje stały limit 2 MB danych. Ustawienia dostawy i regionu są wewnętrznie kopiowane z MCA na wszystkie jego subkonta, więc w przypadku większych multikont klientów możesz szybko wyczerpać limit miejsca na dane. W tym przypadku można obejść ten problem, zarządzając regions i shippingsettings na poziomie identyfikatora sprzedawcy. Nie ma sposobu, aby zwiększyć limit regionów ponad limit 2 MB.

Tworzenie regionu z użyciem celów geograficznych

W przypadku regionów w Brazylii i Rosji możesz też użyć metody regions.create, aby utworzyć region zdefiniowany jako zbiór celów geograficznych, czyli wstępnie zdefiniowanych obszarów geograficznych. Przykłady typów kierowania geograficznego to kraje, województwa, miasta, dzielnice i lotniska. Jednak usługa regions obecnie obsługuje tylko typ „Stan” w przypadku Brazylii i typ „Region” w przypadku Rosji. Aby pobrać plik CSV zawierający wszystkie identyfikatory geograficzne, w tym te, których można używać z usługą regions, przeczytaj artykuł o celach geograficznych. W przykładzie poniżej tworzysz nowy region, podając identyfikatory kierowania geograficznego 3 stanów brazylijskich.

Aby utworzyć region, wyślij żądanie POST, korzystając z tego adresu 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żywaj regionów do tworzenia zastąpień cen regionalnych

Gdy tworzysz region, usługa regions zwraca obiekt odpowiedzi zawierający regionId i 2 pola stanu uprawnień. Jeśli wartość regionalInventoryEligible to true, możesz użyć usługi regionaliventory, aby utworzyć zastąpienie ustawiające inną cenę dla danego regionu. Poniższy przykład pokazuje zastąpienie ceny regionalnej za pomocą regionu opartego na kodzie pocztowym utworzonego w przykładzie powyżej, dla którego regionId ma wartość „456789”.

Aby utworzyć zastąpienie, wyślij żądanie POST, używając tego adresu 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”
}