Bölge gruplandırmayı yönetme

Merchant API bölgesi, accounts.products.regionalInventories kaynağıyla ilgili hedef olarak kullanabileceğiniz coğrafi bir bölgeyi temsil eder. Bölgeleri, posta kodlarının koleksiyonları olarak veya bazı ülkelerde önceden tanımlanmış coğrafi hedefleri kullanarak tanımlayabilirsiniz. Daha fazla bilgi için Bölgeleri ayarlama başlıklı makaleyi inceleyin.

Merchant API, bölgelerinizi yönetmek için toplu uç noktalar sağlar. Bu sayede tek bir API çağrısında 100'e kadar bölge oluşturabilir, güncelleyebilir ve silebilirsiniz. Bu özellik, bölgesel stok durumu ve fiyatlandırmayı (RAAP) geniş ölçekte yöneten satıcılar için idealdir. Verimliliği artırır ve entegrasyonu basitleştirir.

Genel Bakış

Batch API, ilişkili yöntemlerle aşağıdakileri yapmanıza olanak tanır:

  • Tek bir istekte birden fazla bölge oluşturma: regions:batchCreate
  • Birden fazla bölgeyi aynı anda silme: regions:batchDelete
  • Aynı anda birden fazla bölgeyi güncelleme: regions:batchUpdate

Ön koşullar

Tüm toplu istekler, kimlik doğrulama için ADMIN kullanıcı rolünü gerektirir.

Birden fazla bölge oluşturma

Bu örnekte, tek bir BatchCreateRegions çağrısında biri posta kodlarıyla, diğeri ise coğrafi hedeflemeyle tanımlanan iki yeni bölgenin nasıl oluşturulacağı gösterilmektedir.

İstek

İstek URL'sini aşağıdaki gibi oluşturun:

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

İstek gövdesi, her nesnenin bir regionId ve oluşturulacak region verilerini belirttiği bir requests listesi içerir.

{
  "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"
          ]
        }
      }
    }
  ]
}

Yanıt

Başarılı bir istek, yeni region nesnelerinin listesini döndürür.

{
  "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
    }
  ]
}

Aşağıdaki örnekte, toplu istekte birden fazla bölgenin nasıl oluşturulacağı gösterilmektedir:

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

Birden fazla bölgeyi güncelleme

Bu örnekte, mevcut iki bölge için displayName ve postalCodeArea değerlerini güncellemek üzere BatchUpdateRegions yönteminin nasıl kullanılacağı gösterilmektedir. Hedeflenen bölgeyi güncellemek için region.name sağlamanız gerekir.

İstek

İstek URL'sini aşağıdaki gibi oluşturun:

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

İstek gövdesi, requests listesi içeriyor. Her nesne, güncellenecek region verilerini belirtmelidir. region.name alanı, güncellenecek bölgenin kimliğini (ör. "98005") içermelidir. Kaynağı accounts/{ACCOUNT_ID}/regions/name yerine name olarak belirtin. Değiştirilecek alanları belirtmek için updateMask eklemek isteğe bağlıdır.

{
  "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"
    }
  ]
}

Yanıt

Başarılı bir istek, güncellenen region nesnelerinin listesini döndürür.

{
  "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
    }
  ]
}

Aşağıdaki örnekte, toplu istekte birden fazla bölgenin nasıl güncelleneceği gösterilmektedir:

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

Birden çok bölgeyi silme

Tek bir çağrıda birden fazla bölgeyi silebilirsiniz.

İstek

Bu örnekte, tek bir çağrıda iki bölgeyi silmek için BatchDeleteRegions yönteminin nasıl kullanılacağı gösterilmektedir.

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

İstek gövdesi, her nesnenin silinecek bölgenin name ("accounts/{ACCOUNT_ID}/regions/" olmadan) değerini belirttiği bir requests listesi içerir.

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

Yanıt

Başarılı bir istek, boş bir yanıt gövdesi döndürür. Bu, belirtilen bölgelerin silindiğini (veya mevcut olmadığını) gösterir.

{}

Aşağıdaki örnekte, toplu istekte birden fazla bölgenin nasıl silineceği gösterilmektedir:

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

Sınırlamalar

Başlamadan önce şu kuralları göz önünde bulundurun:

  • Atomik işlemler: Toplu istekler atomiktir. Gruptaki tek bir işlem bile başarısız olursa (ör. bir bölge oluşturulamazsa) grubun tamamı başarısız olur ve hiçbir değişiklik yapılmaz. API, hatanın nedenini ayrıntılı olarak açıklayan bir hata döndürür.
  • Toplu işlem sınırları: Her toplu istek en fazla 100 bölge işlemi içerebilir.
  • Kotalar: Bu uç noktalar, tek işlemli muadilleriyle (regions.create, regions.delete, regions.update) aynı kota gruplarını kullanır.

Sık karşılaşılan hatalar ve sorunlar

Sık karşılaşılan birkaç sorun ve çözümleri aşağıda açıklanmıştır.

"The number of requests in a batch is too large" (Bir gruptaki istek sayısı çok fazla)

Bu hata, istek dizinizdeki işlem sayısı 100 sınırını aşarsa ortaya çıkar.

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

Bu sorunu düzeltmek için işlemlerinizi 100 veya daha az sayıda toplu isteğe bölün.

Zorunlu alan boş bırakılmış

Bu hata, zorunlu bir alan eksik olduğunda ortaya çıkar. Hata mesajında eksik parametre belirtilir.

Hata mesajları aşağıdaki gibidir:

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

Bu sorunu düzeltmek için her işlemde tüm zorunlu alanların bulunduğundan emin olun. Örneğin, bir batchUpdate isteğindeki her giriş region.name içermelidir. Aşağıdaki isteğin yayınlanması hataya neden olur:

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

"Belirtilen kimliğe sahip bölge zaten mevcut"

Mevcut bir regionId ile bölge oluşturmaya çalışırsanız hata oluşur.

Hata mesajı: [regionId] Region with specified id already exists..

Bu sorunu düzeltmek için tüm regionId değerlerinin grupta benzersiz olduğunu ve mevcut bölgelerle çakışmadığını doğrulayın.

"region.name veya regionId alanı için yinelenen değer bulundu"

Tek bir toplu istekte aynı kimliğe sahip birden fazla bölge oluşturmaya veya güncellemeye çalışırsanız hata oluşur.

Hata mesajı: Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

Bu sorunu düzeltmek için tek bir toplu istekteki tüm regionId (batchCreate için) veya region.name (batchUpdate için) değerlerinin benzersiz olduğunu doğrulayın.

"Öğe bulunamadı"

batchUpdate kullanılırken istekte belirtilen bölgelerden herhangi biri mevcut değilse tüm grup 404 NOT_FOUND hatasıyla başarısız olur. Bu, mevcut olmayan bölgeler için başarılı olan batchDelete yönteminden farklıdır.

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

Bu sorunu düzeltmek için isteği göndermeden önce güncellemeye çalıştığınız tüm bölgelerin mevcut olduğunu doğrulayın.

Önceki
Create and update regions