রিজিয়ন ব্যাচিং ম্যানেজ করা

Merchant API অঞ্চল বলতে এমন ভৌগোলিক অঞ্চলকে বোঝায় যা আপনি accounts.products.regionalInventories রিসোর্সের সাথে সম্পর্কিত টার্গেট হিসেবে ব্যবহার করতে পারবেন। আপনি পিন কোড বা কিছু দেশে, আগে থেকে নির্দিষ্ট জিওটার্গেট ব্যবহার করে অঞ্চলকে সংগ্রহ হিসেবে সংজ্ঞায়িত করতে পারেন। আরও তথ্যের জন্য, অঞ্চল সেট-আপ করুন দেখুন।

আপনার অঞ্চল ম্যানেজ করার জন্য Merchant API ব্যাচ এন্ডপয়েন্ট প্রদান করে, যা আপনাকে একটি API কলে সর্বাধিক ১০০টি অঞ্চল তৈরি, আপডেট ও মুছে দিতে পারে। যেসব মার্চেন্ট বেশি পরিমাণে আঞ্চলিক উপলভ্যতা ও দাম (RAAP) ম্যানেজ করেন, তাদের জন্য এটি আদর্শ। এর ফলে দক্ষতা বাড়ে এবং ইন্টিগ্রেশন সহজ হয়।

এক নজরে

Batch API আপনাকে সংশ্লিষ্ট পদ্ধতির মাধ্যমে নিম্নলিখিত কাজগুলি করতে দেয়:

  • একটি অনুরোধে একাধিক অঞ্চল তৈরি করুন: regions:batchCreate
  • একসাথে একাধিক অঞ্চল মুছে দিতে: regions:batchDelete
  • একসাথে একাধিক অঞ্চল আপডেট করুন: regions:batchUpdate

পূর্বশর্ত

যাচাইকরণের জন্য সব ব্যাচ অনুরোধে ADMIN ব্যবহারকারীর ভূমিকা প্রয়োজন।

একাধিক অঞ্চল তৈরি করা

এই উদাহরণে দেখানো হয়েছে যে কীভাবে BatchCreateRegions-এর একটি কলে দুটি নতুন অঞ্চল তৈরি করা যায় — একটি পিন কোড দ্বারা এবং অন্যটি জিও টার্গেটিং দ্বারা সংজ্ঞায়িত করা হয়।

অনুরোধ করুন

নিম্নলিখিতভাবে অনুরোধ URL তৈরি করুন:

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

অনুরোধের বডিতে requests-এর একটি তালিকা থাকে, যেখানে প্রতিটি অবজেক্ট একটি regionId এবং তৈরি করার জন্য region ডেটা নির্দিষ্ট করে।

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

রেসপন্স

অনুরোধ সফল হলে, নতুন region অবজেক্টের একটি তালিকা রিটার্ন করা হয়।

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

নিম্নলিখিত নমুনা থেকে বোঝা যায় যে কীভাবে ব্যাচ অনুরোধে একাধিক অঞ্চল তৈরি করতে হয়:

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

একাধিক অঞ্চল আপডেট করা

এই উদাহরণে দেখানো হয়েছে যে কীভাবে দুটি আগে থেকে থাকা অঞ্চলের জন্য displayName এবং postalCodeArea আপডেট করতে BatchUpdateRegions ব্যবহার করতে হয়। টার্গেট করা অঞ্চল আপডেট করতে আপনাকে অবশ্যই region.name প্রদান করতে হবে।

অনুরোধ করুন

নিম্নলিখিতভাবে অনুরোধ URL তৈরি করুন:

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

অনুরোধের বডিতে requests-এর একটি তালিকা রয়েছে। আপডেট করার জন্য প্রতিটি অবজেক্টকে region ডেটা উল্লেখ করতে হবে। আপডেট করার জন্য region.name ফিল্ডে অবশ্যই অঞ্চলের আইডি থাকতে হবে, যেমন,"98005"। accounts/{ACCOUNT_ID}/regions/name-এর পরিবর্তে রিসোর্সকে name হিসেবে উল্লেখ করুন। পরিবর্তন করতে হবে এমন ফিল্ড বোঝাতে updateMask যোগ করা ঐচ্ছিক।

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

রেসপন্স

অনুরোধ সফল হলে, আপডেট করা region অবজেক্টের একটি তালিকা রিটার্ন করা হয়।

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

নিচের নমুনা থেকে কীভাবে ব্যাচ অনুরোধে একাধিক অঞ্চল আপডেট করতে হয় তা জানুন:

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

একাধিক অঞ্চল মুছে দেওয়া

আপনি একটি কলে একাধিক অঞ্চল মুছে দিতে পারবেন।

অনুরোধ করুন

এই উদাহরণে দেখানো হয়েছে, কীভাবে BatchDeleteRegions ব্যবহার করে একটি কলের মধ্যে দুটি অঞ্চল মুছে দিতে হয়।

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

অনুরোধের বডিতে requests-এর একটি তালিকা থাকে, যেখানে প্রতিটি অবজেক্ট মুছে ফেলার জন্য অঞ্চলের name ("accounts/{ACCOUNT_ID}/regions/" ছাড়া) নির্দিষ্ট করে।

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

রেসপন্স

সফল অনুরোধের ক্ষেত্রে, খালি রেসপন্স বডি রিটার্ন করা হয়, যা থেকে বোঝা যায় যে উল্লিখিত অঞ্চলগুলি মুছে দেওয়া হয়েছে (বা সেগুলি ছিল না)।

{}

নিচের নমুনা থেকে বোঝা যায় যে কীভাবে ব্যাচ অনুরোধে একাধিক অঞ্চল মুছে দিতে হয়:

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

সীমাবদ্ধতা

শুরু করার আগে, এইসব নিয়ম মনে রাখবেন:

  • অ্যাটমিক অপারেশন: ব্যাচ অনুরোধ অ্যাটমিক হয়। ব্যাচের মধ্যে কোনও একটি অপারেশন কাজ না করলে (যেমন, একটি অঞ্চল তৈরি করা না গেলে), পুরো ব্যাচটি কাজ করবে না এবং কোনও পরিবর্তন করা হবে না। API একটি সমস্যা রিটার্ন করবে যাতে ব্যর্থতার কারণের বিবরণ থাকবে।
  • ব্যাচ সীমা: প্রতিটি ব্যাচ অনুরোধে সর্বাধিক ১০০টি অঞ্চল অপারেশন থাকতে পারে।
  • কোটা: এই এন্ডপয়েন্টগুলি তাদের সিঙ্গেল-অপারেশন সমকক্ষদের মতো একই কোটা গ্রুপ ব্যবহার করে (regions.create, regions.delete, regions.update)।

সাধারণ সমস্যা ও তার সমাধান

এখানে কিছু সাধারণ সমস্যা ও তার সমাধান দেওয়া হল।

"ব্যাচে অনুরোধের সংখ্যা খুব বেশি"

আপনার অনুরোধের অ্যারেতে অপারেশনের সংখ্যা ১০০-এর বেশি হলে এই সমস্যা হয়।

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

এটি সমাধান করতে, আপনার অপারেশনকে ১০০ বা তার কম সংখ্যক একাধিক ব্যাচ অনুরোধে ভাগ করুন।

প্রয়োজনীয় ফিল্ড নেই

প্রয়োজনীয় ফিল্ডে তথ্য না দিলে এই সমস্যা হয়। সমস্যার মেসেজে অনুপস্থিত প্যারামিটার উল্লেখ করা আছে।

সমস্যার মেসেজগুলি নিচে দেওয়া হল:

  • batchCreate-এর জন্য: [regionId] Required parameter: regionId
  • batchUpdate-এর জন্য: [region.name] Required field not provided.
  • batchDelete-এর জন্য: [name] Required parameter: name

এটি সমাধান করতে, প্রতিটি অপারেশনে প্রয়োজনীয় সব ফিল্ড আছে কিনা তা যাচাই করুন। যেমন, batchUpdate অনুরোধের প্রতিটি এন্ট্রিতে region.name থাকতে হবে। নিম্নলিখিত অনুরোধ পোস্ট করলে একটি সমস্যা হয়:

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

"নির্দিষ্ট আইডি সহ অঞ্চল আগে থেকেই আছে"

আপনি যদি এমন regionId সহ কোনও অঞ্চল তৈরি করার চেষ্টা করেন যা আগে থেকেই বিদ্যমান, তাহলে একটি সমস্যা হয়।

সমস্যার মেসেজ হল [regionId] Region with specified id already exists..

এটি সমাধান করতে, যাচাই করুন যে ব্যাচের মধ্যে সমস্ত regionId মান অনন্য এবং আগে থেকে থাকা অঞ্চলের সাথে কোনও বিরোধ নেই।

"ফিল্ড region.name বা regionId-এর জন্য ডুপ্লিকেট ভ্যালু পাওয়া গেছে"

একটি ব্যাচ অনুরোধের মধ্যে একই আইডি সহ একাধিক অঞ্চল তৈরি বা আপডেট করার চেষ্টা করলে সমস্যা হয়।

সমস্যার মেসেজ হল Duplicate value found for field {fieldName} in this batch request with value {duplicated_value}..

এটি সমাধান করতে, যাচাই করুন যে একটি ব্যাচ অনুরোধের মধ্যে সমস্ত regionId (batchCreate-এর জন্য) বা region.name (batchUpdate-এর জন্য) ভ্যালু অনন্য।

"আইটেম খুঁজে পাওয়া যায়নি"

batchUpdate ব্যবহার করার সময়, অনুরোধে উল্লেখ করা কোনও অঞ্চল না থাকলে, 404 NOT_FOUND সমস্যার কারণে পুরো ব্যাচটি কাজ করবে না। এটি batchDelete-এর থেকে আলাদা, যা অস্তিত্বহীন অঞ্চলের ক্ষেত্রে সফল হয়।

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

এটি সমাধান করতে, অনুরোধ পাঠানোর আগে আপনি আপডেট করতে চাইছেন এমন সব অঞ্চল আছে কিনা তা যাচাই করে দেখুন।

পূর্ববর্তী
Create and update regions
পরবর্তী
Manage Merchant Center email preferences