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 lub (w niektórych krajach) za pomocą wstępnie zdefiniowanych miejsc docelowych geograficznych. W tym przewodniku znajdziesz przykłady definiowania poszczególnych typów regionów oraz tworzenia zastąpień cen regionalnych. Więcej informacji o usłudze regions, w tym o wszystkich dostępnych metodach i parametrach, znajdziesz w dokumentacji.
Wymagania dotyczące regionów
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 pomyślnego wywołania regions.create zawiera 2 pola logiczne: regionalInventoryEligible i shippingEligible, które wskazują, czy możesz używać danego regionu z usługami regionalinventory i shippingsettings.
regionalInventoryEligible
Aby można było używać usługi regionalinventory, region musi spełniać te kryteria:
- Pole
regionId, które określasz podczas tworzenia regionu, może zawierać tylko cyfry i co najmniej 6 cyfr. - Region musi spełniać wymagania dotyczące minimalnej wielkości obszaru geograficznego i liczby online.
shippingEligible
Aby można było używać usługi shippingsettings, region musi spełniać te kryteria:
- Region należy określić za pomocą kodów pocztowych.
- Region musi być częścią kraju obsługiwanego przez usługę
shippingsettings.
Próbki
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
Za pomocą metody regions.create możesz utworzyć region zdefiniowany jako zbiór kodów pocztowych. Poniższy przykład pokazuje nowy region dla amerykańskiego stanu Arizona, 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 koncie Merchant Center obowiązuje stały limit 2 MB danych dla konta regions i shippingsettings. Ustawienia dostawy i regionu są kopiowane z multikonta klientów na wszystkie jego subkonta, więc w przypadku większych multikont klientów możesz szybko osiągnąć limit miejsca na dane. W takim przypadku obejściem problemu jest zarządzanie regions i shippingsettings na poziomie identyfikatora sprzedawcy. Nie można zwiększyć limitu regionów powyżej limitu 2 MB.
Tworzenie regionu za pomocą 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, które są wstępnie zdefiniowanymi obszarami geograficznymi. Przykłady typów kierowania geograficznego to kraje, stany, miasta, dzielnice i lotniska. Jednak usługa regions obsługuje obecnie tylko typ „Stan” w przypadku Brazylii i „Region” w przypadku Rosji. Aby pobrać plik CSV ze wszystkimi identyfikatorami kierowania geograficznego, w tym z docelowymi lokalizacjami geograficznymi, których można używać z usługą regions, przeczytaj sekcję Kierowanie geograficzne. W poniższym przykładzie tworzymy nowy region, podając identyfikatory kierowania geograficznego 3 stanów w Brazylii.
Aby utworzyć region, wyślij żądanie POST przy użyciu tego adresu URL i treść żądania:
https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456
{
geoTargetAreas: {
geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
}
}
Użyj regionów do tworzenia regionalnych zastąpień cen
Po utworzeniu regionu usługa regions zwraca obiekt odpowiedzi zawierający 2 pola stanu regionId i 2 pola stanu uprawnień. Jeśli regionalInventoryEligible ma wartość true, możesz użyć usługi regionaliventory, aby utworzyć zastąpienie, które ustawia inną cenę dla danego regionu. Poniższy przykład pokazuje zastąpienie ceny regionalnej z użyciem regionu opartego na kodzie pocztowym utworzonego w powyższym przykładzie, który ma regionId o wartości „456789”.
Aby utworzyć zastąpienie, wyślij żądanie POST, korzystając z 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”
}