Mengelola pengelompokan wilayah

Wilayah Merchant API mewakili wilayah geografis yang dapat Anda gunakan sebagai target yang terkait dengan resource accounts.products.regionalInventories. Anda dapat menentukan wilayah sebagai kumpulan kode pos atau, di beberapa negara, menggunakan geotarget yang telah ditentukan sebelumnya. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan wilayah.

Merchant API menyediakan endpoint batch untuk mengelola wilayah, sehingga Anda dapat membuat, memperbarui, dan menghapus hingga 100 wilayah dalam satu panggilan API. Fitur ini ideal bagi penjual yang mengelola ketersediaan dan harga regional (RAAP) dalam skala besar, sehingga meningkatkan efisiensi dan menyederhanakan integrasi.

Ringkasan

Batch API memungkinkan Anda melakukan hal berikut dengan metode terkait:

• Membuat beberapa wilayah dalam satu permintaan: regions:batchCreate
• Menghapus beberapa wilayah sekaligus: regions:batchDelete
• Perbarui beberapa wilayah secara bersamaan: regions:batchUpdate

Prasyarat

Semua permintaan batch memerlukan peran pengguna ADMIN untuk autentikasi.

Membuat beberapa wilayah

Contoh ini menunjukkan cara membuat dua wilayah baru — satu ditentukan oleh kode pos dan satu lagi oleh penargetan geografis — dalam satu panggilan BatchCreateRegions.

Permintaan

Buat URL permintaan sebagai berikut:

POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchCreate

Isi permintaan berisi daftar requests, di mana setiap objek menentukan regionId dan data region yang akan dibuat.

{
  "requests": [
    {
      "regionId": "seattle-area-98340",
      "region": {
        "displayName": "Seattle Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "98340"
            }
          ]
        }
      }
    },
    {
      "regionId": "co-de-states",
      "region": {
        "displayName": "Colorado and Delaware",
        "geoTargetArea": {
          "geotargetCriteriaIds": [
            "21138",
            "21141"
          ]
        }
      }
    }
  ]
}

Respons

Permintaan yang berhasil akan menampilkan daftar objek region baru.

{
  "regions": [
    {
      "name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
      "displayName": "Seattle Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "98340"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    },
    {
      "name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
      "displayName": "Colorado and Delaware",
      "geotargetArea": {
        "geotargetCriteriaIds": [
          "21138",
          "21141"
        ]
      },
      "regionalInventoryEligible": false,
      "shippingEligible": false
    }
  ]
}

Contoh berikut menunjukkan cara membuat beberapa wilayah dalam permintaan batch:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchCreateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.CreateRegionRequest;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea;
import com.google.shopping.merchant.accounts.v1.Region.PostalCodeArea.PostalCodeRange;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to create multiple regions for a Merchant Center account. */
public class BatchCreateRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  public static void batchCreateRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to insert the regions.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<CreateRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            CreateRegionRequest.newBuilder()
                .setParent(parent)
                .setRegionId(regionId)
                .setRegion(
                    Region.newBuilder()
                        .setDisplayName("Region " + regionId)
                        .setPostalCodeArea(
                            PostalCodeArea.newBuilder()
                                .setRegionCode("US")
                                .addPostalCodes(
                                    PostalCodeRange.newBuilder()
                                        .setBegin("10001")
                                        .setEnd("10282")
                                        .build())
                                .build())
                        .build())
                .build());
      }

      BatchCreateRegionsRequest request =
          BatchCreateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Create Regions request");
      BatchCreateRegionsResponse response = regionsServiceClient.batchCreateRegions(request);
      System.out.println("Inserted Regions Names below");
      // The last part of the region name will be the ID of the region.
      // Format: `accounts/{account}/region/{region}`
      response.getRegionsList().forEach(region -> System.out.println(region.getName()));

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to create.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchCreateRegions(config, regionIds);
  }
}
BatchCreateRegionsSample.java

Memperbarui beberapa wilayah

Contoh ini menunjukkan cara menggunakan BatchUpdateRegions untuk memperbarui displayName dan postalCodeArea untuk dua wilayah yang ada. Anda harus memberikan region.name untuk memperbarui wilayah target.

Catatan: Anda hanya dapat memperbarui nama wilayah menggunakan antarmuka pengguna Merchant Center.

Permintaan

Buat URL permintaan sebagai berikut:

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchUpdate

Isi permintaan berisi daftar requests. Setiap objek harus menentukan data region yang akan diperbarui. Kolom region.name harus berisi ID wilayah yang akan diperbarui, misalnya,"98005". Tentukan resource sebagai name, bukan accounts/{ACCOUNT_ID}/regions/name. Menyertakan updateMask untuk menunjukkan kolom yang akan diubah bersifat opsional.

{
  "requests": [
    {
      "region": {
        "name": "98005",
        "displayName": "Seattle Updated Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "98330"
            }
          ]
        }
      },
      "updateMask": "displayName,postalCodeArea"
    },
    {
      "region": {
        "name": "07086",
        "displayName": "NewYork Updated Region",
        "postalCodeArea": {
          "regionCode": "US",
          "postalCodes": [
            {
              "begin": "11*"
            }
          ]
        }
      },
      "updateMask": "displayName,postalCodeArea"
    }
  ]
}

Respons

Permintaan yang berhasil akan menampilkan daftar objek region yang diperbarui.

{
  "regions": [
    {
      "name": "accounts/{ACCOUNT_ID}/regions/98005",
      "displayName": "Seattle Updated Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "98330"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    },
    {
      "name": "accounts/{ACCOUNT_ID}/regions/07086",
      "displayName": "NewYork Updated Region",
      "postalCodeArea": {
        "regionCode": "US",
        "postalCodes": [
          {
            "begin": "11*"
          }
        ]
      },
      "regionalInventoryEligible": true,
      "shippingEligible": true
    }
  ]
}

Contoh berikut menunjukkan cara memperbarui beberapa wilayah dalam permintaan batch:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsRequest;
import com.google.shopping.merchant.accounts.v1.BatchUpdateRegionsResponse;
import com.google.shopping.merchant.accounts.v1.Region;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import com.google.shopping.merchant.accounts.v1.UpdateRegionRequest;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to update multiple regions for a Merchant Center account. */
public class BatchUpdateRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String getRegionName(String accountId, String regionId) {
    return String.format("accounts/%s/regions/%s", accountId, regionId);
  }

  public static void batchUpdateRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to update the regions.
    String parent = getParent(config.getAccountId().toString());
    String accountId = config.getAccountId().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<UpdateRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            UpdateRegionRequest.newBuilder()
                .setRegion(
                    Region.newBuilder()
                        .setName(getRegionName(accountId, regionId))
                        .setDisplayName("Updated Region " + regionId)
                        .build())
                .setUpdateMask(FieldMask.newBuilder().addPaths("display_name").build())
                .build());
      }

      BatchUpdateRegionsRequest request =
          BatchUpdateRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Update Regions request");
      BatchUpdateRegionsResponse response = regionsServiceClient.batchUpdateRegions(request);
      System.out.println("Updated Regions Names below");
      // The last part of the region name will be the ID of the region.
      // Format: `accounts/{account}/region/{region}`
      response.getRegionsList().forEach(region -> System.out.println(region.getName()));

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to update.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchUpdateRegions(config, regionIds);
  }
}
BatchUpdateRegionsSample.java

Menghapus beberapa wilayah

Anda dapat menghapus beberapa wilayah dalam satu panggilan.

Catatan: Operasi penghapusan bersifat idempoten. Mencoba menghapus region yang tidak ada tidak akan menyebabkan error.

Permintaan

Contoh ini menunjukkan cara menggunakan BatchDeleteRegions untuk menghapus dua region dalam satu panggilan.

POST
https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/regions:batchDelete

Isi permintaan berisi daftar requests, dengan setiap objek menentukan name (tanpa "accounts/{ACCOUNT_ID}/regions/") region yang akan dihapus.

{
  "requests":
   [
    {
      "name": "98005"
    },
    {
      "name": "07086"
    }
   ]
}

Respons

Permintaan yang berhasil akan menampilkan isi respons kosong, yang menunjukkan bahwa wilayah yang ditentukan telah dihapus (atau tidak ada).

{}

Contoh berikut menunjukkan cara menghapus beberapa wilayah dalam permintaan batch:

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1.BatchDeleteRegionsRequest;
import com.google.shopping.merchant.accounts.v1.DeleteRegionRequest;
import com.google.shopping.merchant.accounts.v1.RegionsServiceClient;
import com.google.shopping.merchant.accounts.v1.RegionsServiceSettings;
import java.util.ArrayList;
import java.util.List;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to delete multiple regions for a Merchant Center account. */
public class BatchDeleteRegionsSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String getRegionName(String accountId, String regionId) {
    return String.format("accounts/%s/regions/%s", accountId, regionId);
  }

  public static void batchDeleteRegions(Config config, List<String> regionIds) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    RegionsServiceSettings regionsServiceSettings =
        RegionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to delete the regions.
    String parent = getParent(config.getAccountId().toString());
    String accountId = config.getAccountId().toString();

    // Calls the API and catches and prints any network failures/errors.
    try (RegionsServiceClient regionsServiceClient =
        RegionsServiceClient.create(regionsServiceSettings)) {

      List<DeleteRegionRequest> requests = new ArrayList<>();
      for (String regionId : regionIds) {
        requests.add(
            DeleteRegionRequest.newBuilder().setName(getRegionName(accountId, regionId)).build());
      }

      BatchDeleteRegionsRequest request =
          BatchDeleteRegionsRequest.newBuilder().setParent(parent).addAllRequests(requests).build();

      System.out.println("Sending Batch Delete Regions request");
      regionsServiceClient.batchDeleteRegions(request);
      System.out.println("Regions deleted successfully");

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // The unique IDs of the regions to delete.
    List<String> regionIds = new ArrayList<>();
    regionIds.add("REGION_1");
    regionIds.add("REGION_2");
    regionIds.add("REGION_3");
    regionIds.add("REGION_4");
    regionIds.add("REGION_5");

    batchDeleteRegions(config, regionIds);
  }
}
BatchDeleteRegionsSample.java

Batasan

Sebelum memulai, perhatikan aturan berikut:

• Operasi atomik: Permintaan batch bersifat atomik. Jika satu operasi dalam batch gagal (misalnya, satu region gagal dibuat), seluruh batch akan gagal, dan tidak ada perubahan yang akan dilakukan. API akan menampilkan error yang menjelaskan penyebab kegagalan.
• Batas batch: Setiap permintaan batch dapat berisi maksimum 100 operasi wilayah.
• Kuota: Endpoint ini menggunakan grup kuota yang sama dengan endpoint operasi tunggalnya (regions.create, regions.delete, regions.update).

Error dan masalah umum

Berikut beberapa kesalahan umum dan solusinya.

"The number of requests in a batch is too large" (Jumlah permintaan dalam batch terlalu besar)

Error ini terjadi jika jumlah operasi dalam array permintaan Anda melebihi batas 100.

"error":
  {
    "code": 400,
    "message": "The number of requests in a batch is too large.",
    "status": "INVALID_ARGUMENT"
  }

Untuk memperbaikinya, bagi operasi Anda menjadi beberapa permintaan batch yang masing-masing berisi 100 atau kurang.

Bidang wajib belum diisi

Error ini terjadi saat kolom wajib diisi tidak ada. Pesan error menentukan parameter yang tidak ada.

Pesan errornya adalah sebagai berikut:

• Untuk batchCreate: [regionId] Required parameter: regionId
• Untuk batchUpdate: [region.name] Required field not provided.
• Untuk batchDelete: [name] Required parameter: name

Untuk memperbaikinya, pastikan semua kolom wajib diisi ada di setiap operasi. Misalnya, setiap entri dalam permintaan batchUpdate harus menyertakan region.name. Memposting permintaan berikut akan menghasilkan error:

{
  "requests":
  [
    {
      "region":
        {
          "displayName": "An update without a region name"
        },
        "updateMask": "displayName"
    }
  ]
}

"Wilayah dengan ID yang ditentukan sudah ada"

Error terjadi jika Anda mencoba membuat wilayah dengan regionId yang sudah ada.

Pesan errornya adalah [regionId] Region with specified id already exists..

Untuk memperbaikinya, pastikan semua nilai regionId unik dalam batch dan tidak bertentangan dengan wilayah yang ada.

"Nilai duplikat ditemukan untuk kolom region.name atau regionId"

Error akan terjadi jika Anda mencoba membuat atau memperbarui beberapa wilayah dengan ID yang sama dalam satu permintaan batch.

Pesan errornya adalah Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

Untuk memperbaikinya, pastikan semua nilai regionId (untuk batchCreate) atau region.name (untuk batchUpdate) bersifat unik dalam satu permintaan batch.

"Item tidak ditemukan"

Saat menggunakan batchUpdate, jika ada wilayah yang ditentukan dalam permintaan tidak ada, seluruh batch akan gagal dengan error 404 NOT_FOUND. Hal ini berbeda dengan batchDelete, yang berhasil untuk wilayah yang tidak ada.

"error": {
    "code": 404,
    "message": "item not found",
    "status": "NOT_FOUND"
}

Untuk memperbaikinya, verifikasi bahwa semua wilayah yang Anda coba perbarui ada sebelum mengirim permintaan.