इलाके के हिसाब से बैच बनाने की सुविधा मैनेज करना

Merchant API क्षेत्र, एक भौगोलिक क्षेत्र को दिखाता है. इसका इस्तेमाल accounts.products.regionalInventories संसाधन से जुड़े टारगेट के तौर पर किया जा सकता है. पिन कोड के कलेक्शन के तौर पर क्षेत्रों को तय किया जा सकता है. इसके अलावा, कुछ देशों में पहले से तय किए गए जियोटारगेट का इस्तेमाल करके भी क्षेत्रों को तय किया जा सकता है. ज़्यादा जानकारी के लिए, क्षेत्र सेट अप करना लेख पढ़ें.

Merchant API, क्षेत्रों को मैनेज करने के लिए बैच एंडपॉइंट उपलब्ध कराता है. इससे एक ही एपीआई कॉल में, ज़्यादा से ज़्यादा 100 क्षेत्रों को बनाया, अपडेट किया, और मिटाया जा सकता है. यह सुविधा, उन कारोबारियों या कंपनियों के लिए सबसे सही है जो बड़े पैमाने पर क्षेत्र के हिसाब से प्रॉडक्ट की उपलब्धता और कीमत (आरएएपी) को मैनेज करती हैं. इससे उन्हें बेहतर तरीके से काम करने और इंटिग्रेशन को आसान बनाने में मदद मिलती है.

खास जानकारी

Batch API की मदद से, इन तरीकों का इस्तेमाल करके ये काम किए जा सकते हैं:

  • एक ही अनुरोध में कई क्षेत्र बनाएं: regions:batchCreate
  • एक साथ कई इलाके मिटाने के लिए: regions:batchDelete
  • एक साथ कई क्षेत्रों को अपडेट करें: regions:batchUpdate

ज़रूरी शर्तें

सभी बैच अनुरोधों के लिए, पुष्टि करने के लिए ADMIN उपयोगकर्ता की भूमिका ज़रूरी होती है.

एक से ज़्यादा क्षेत्र बनाना

इस उदाहरण में, BatchCreateRegions के एक ही कॉल में दो नए क्षेत्र बनाने का तरीका दिखाया गया है. इनमें से एक क्षेत्र को पिन कोड के हिसाब से और दूसरे को जियो टारगेटिंग के हिसाब से तय किया गया है.

अनुरोध

अनुरोध यूआरएल इस तरह बनाएं:

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 देना होगा.

अनुरोध

अनुरोध यूआरएल इस तरह बनाएं:

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

सीमाएं

शुरू करने से पहले, इन नियमों का ध्यान रखें:

  • ऐटॉमिक कार्रवाइयां: बैच अनुरोध ऐटॉमिक होते हैं. अगर बैच में मौजूद किसी एक कार्रवाई में गड़बड़ी होती है (उदाहरण के लिए, कोई क्षेत्र नहीं बनाया जा सका), तो पूरा बैच काम नहीं करेगा और कोई बदलाव नहीं किया जाएगा. एपीआई, गड़बड़ी की वजह के बारे में जानकारी देगा.
  • बैच के लिए सीमाएं: बैच में किए गए हर अनुरोध में, ज़्यादा से ज़्यादा 100 क्षेत्र से जुड़ी कार्रवाइयां हो सकती हैं.
  • कोटा: ये एंडपॉइंट, एक बार में एक ऑपरेशन करने वाले एंडपॉइंट के जैसे ही कोटा ग्रुप का इस्तेमाल करते हैं (regions.create, regions.delete, regions.update).

आम तौर पर होने वाली गड़बड़ियां और समस्याएं

यहां कुछ सामान्य समस्याएं और उनके समाधान दिए गए हैं.

"एक साथ भेजे गए अनुरोधों की संख्या बहुत ज़्यादा है"

यह गड़बड़ी तब होती है, जब आपके अनुरोधों की ऐरे में कार्रवाइयों की संख्या 100 की सीमा से ज़्यादा हो जाती है.

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

इस समस्या को ठीक करने के लिए, अपने ऑपरेशनों को 100 या उससे कम के कई बैच अनुरोधों में बांटें.

आवश्यक फ़ील्ड मौजूद नहीं है

यह गड़बड़ी तब होती है, जब कोई ज़रूरी फ़ील्ड मौजूद नहीं होता. गड़बड़ी के मैसेज में, मौजूद न होने वाले पैरामीटर की जानकारी दी गई है.

गड़बड़ी के मैसेज यहां दिए गए हैं:

  • 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 वैल्यू यूनीक हों. साथ ही, वे मौजूदा क्षेत्रों से मेल न खाती हों.

"क्षेत्र के नाम या क्षेत्र के आईडी फ़ील्ड के लिए डुप्लीकेट वैल्यू मिली"

एक ही बैच अनुरोध में, एक ही आईडी से कई क्षेत्र बनाने या अपडेट करने पर गड़बड़ी होती है.

गड़बड़ी का मैसेज 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