Halaman ini diterjemahkan oleh Cloud Translation API.

Wilayah

Layanan regions memungkinkan Anda membuat dan mengelola wilayah geografis yang dapat digunakan sebagai target dengan layanan regionalinventory dan shippingsettings. Anda dapat menentukan wilayah sebagai kumpulan kode pos atau, di beberapa negara, menggunakan target geografis yang telah ditetapkan. Panduan ini memberikan contoh cara menentukan setiap jenis wilayah, serta cara membuat penggantian harga regional. Untuk informasi tambahan tentang layanan regions, termasuk semua metode dan parameter yang tersedia, lihat dokumentasi referensi.

Kelayakan wilayah

Saat Anda membuat suatu wilayah, layanan wilayah menentukan apakah Anda dapat menggunakan wilayah dengan layanan Content API lainnya. Objek respons yang ditampilkan untuk panggilan regions.create yang berhasil mencakup dua kolom boolean, regionalInventoryEligible dan shippingEligible, yang menunjukkan apakah Anda dapat menggunakan region dengan layanan regionalinventory dan shippingsettings masing-masing.

regionalInventoryEligible

Agar memenuhi syarat untuk digunakan dengan layanan regionalinventory, wilayah harus memenuhi kriteria berikut:

regionId, yang Anda tentukan saat membuat wilayah, hanya boleh berisi digit dan harus berisi minimal 6 digit.
Wilayah harus memenuhi persyaratan ukuran minimum untuk populasi online dan area geografis.

shippingEligible

Agar memenuhi syarat untuk digunakan dengan layanan shippingsettings, wilayah harus memenuhi kriteria berikut:

Wilayah harus ditetapkan menggunakan kode pos.
Wilayah harus merupakan bagian dari negara yang didukung oleh layanan shippingsettings.

Contoh

Berikut adalah contoh kode lengkap yang dapat Anda gunakan untuk membuat region baru di 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();
  }
}

Buat wilayah menggunakan kode pos

Anda dapat menggunakan metode regions.create untuk membuat wilayah yang ditetapkan sebagai kumpulan kode pos. Contoh di bawah ini membuat wilayah baru untuk negara bagian Arizona di AS dengan menentukan rentang kode pos.

Untuk membuat wilayah, buat permintaan POST dengan URL berikut dan isi permintaan:

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

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

Ada batas pasti sebesar 2 MB data untuk regions dan shippingsettings per akun Merchant Center. Setelan pengiriman dan region disalin secara internal dari MCA ke semua sub-akunnya, sehingga untuk MCA yang lebih besar, Anda dapat mencapai batas penyimpanan dengan cepat. Dalam kasus ini, solusinya adalah mengelola regions dan shippingsettings di tingkat ID penjual. Tidak ada cara untuk meningkatkan kuota region Anda setelah batas 2 MB.

Membuat wilayah menggunakan target geografis

Untuk wilayah di Brasil dan Rusia, Anda juga dapat menggunakan metode regions.create untuk membuat wilayah yang ditetapkan sebagai kumpulan target geografis, yang merupakan area geografis yang telah ditetapkan sebelumnya. Contoh jenis target geografis mencakup negara, negara bagian, kota, kawasan, dan bandara. Namun, saat ini layanan regions hanya mendukung jenis "Negara Bagian" untuk Brasil dan jenis "Wilayah" untuk Rusia. Untuk mendownload file csv semua ID target geografis, termasuk target geografis yang dapat digunakan dengan layanan regions, lihat Target geografis. Contoh di bawah membuat wilayah baru dengan memberikan ID target geografis dari tiga negara bagian Brasil.

Untuk membuat wilayah, buat permintaan POST menggunakan URL berikut dan isi permintaan:

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

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

Gunakan wilayah untuk membuat penggantian harga regional

Saat Anda membuat wilayah, layanan regions akan menampilkan objek respons yang menyertakan regionId dan dua kolom status kelayakan. Jika nilai regionalInventoryEligible adalah true, Anda dapat menggunakan layanan regionaliventory untuk membuat penggantian yang menetapkan harga yang berbeda untuk wilayah tersebut. Contoh di bawah ini membuat penggantian harga regional menggunakan wilayah berbasis kode pos yang dibuat dalam contoh di atas, yang memiliki regionId "456789".

Untuk membuat penggantian, buat permintaan POST menggunakan URL dan isi permintaan berikut:

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

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