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 target geografis yang telah ditentukan. 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. Hal 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 menyelesaikan hal berikut dengan metode terkait:

  • Membuat beberapa region dalam satu permintaan: regions:batchCreate
  • Menghapus beberapa region sekaligus: regions:batchDelete
  • Perbarui beberapa region 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, dengan 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 region 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);
  }
}

Memperbarui beberapa wilayah

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

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 region 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);
  }
}

Menghapus beberapa wilayah

Anda dapat menghapus beberapa region dalam satu panggilan.

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 region yang ditentukan telah dihapus (atau tidak ada).

{}

Contoh berikut menunjukkan cara menghapus beberapa region 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);
  }
}

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 region.
  • 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"

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 berisi 100 operasi atau kurang.

Bidang wajib belum diisi

Error ini terjadi jika 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 yang 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"
    }
  ]
}

"Region dengan ID yang ditentukan sudah ada"

Error akan terjadi jika Anda mencoba membuat region 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 region 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 region yang ditentukan dalam permintaan tidak ada, seluruh batch akan gagal dengan error 404 NOT_FOUND. Hal ini berbeda dengan batchDelete, yang berhasil untuk region yang tidak ada.

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

Untuk memperbaikinya, pastikan semua region yang ingin Anda perbarui ada sebelum mengirim permintaan.