إدارة تجميع المناطق

تمثّل منطقة Merchant API منطقة جغرافية يمكنك استخدامها كهدف مرتبط بمورد accounts.products.regionalInventories. يمكنك تحديد المناطق كمجموعات من الرموز البريدية أو باستخدام الاستهدافات الجغرافية المحدّدة مسبقًا في بعض البلدان. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد المناطق.

توفّر Merchant API نقاط نهاية مجمّعة لإدارة مناطقك، ما يتيح لك إنشاء ما يصل إلى 100 منطقة وتعديلها وحذفها في طلب واحد من واجهة برمجة التطبيقات. وهذا الخيار مثالي للتجّار الذين يديرون ميزة "تحديد السعر والتوفّر محليًا" على نطاق واسع، ما يحسّن الكفاءة ويبسّط عملية الدمج.

نظرة عامة

تتيح لك 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
    }
  ]
}

يوضّح النموذج التالي كيفية إنشاء مناطق متعددة في طلب مجمّع:

جافا

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

تعديل مناطق متعددة

يوضّح هذا المثال كيفية استخدام BatchUpdateRegions لتعديل displayName وpostalCodeArea لمنطقتَين حاليتَين. يجب تقديم region.name لتعديل المنطقة المستهدَفة.

طلب

أنشئ عنوان URL للطلب على النحو التالي:

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

يحتوي نص الطلب على قائمة من requests. يجب أن يحدّد كل عنصر بيانات region المطلوب تعديلها. يجب أن يحتوي حقل region.name على رقم تعريف المنطقة المطلوب تعديلها، على سبيل المثال "98005". حدِّد المورد على أنّه name بدلاً من accounts/{ACCOUNT_ID}/regions/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
    }
  ]
}

يوضّح النموذج التالي كيفية تعديل مناطق متعددة في طلب مجمّع:

جافا

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

الردّ

يعرض الطلب الناجح نص استجابة فارغًا، ما يشير إلى أنّه تم حذف المناطق المحدّدة (أو أنّها لم تكن موجودة).

{}

يوضّح النموذج التالي كيفية حذف مناطق متعددة في طلب مجمّع:

جافا

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 فريدة ضمن الدفعة ولا تتعارض مع المناطق الحالية.

"تم العثور على قيمة مكرّرة للحقل 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