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.