مدیریت دسته‌بندی منطقه

منطقه Merchant API نشان‌دهنده منطقه جغرافیایی است که می‌توانید به‌عنوان هدف مرتبط با منبع accounts.products.regionalInventories استفاده کنید. می‌توانید مناطق را به‌عنوان مجموعه‌ای از کدهای پستی یا، در برخی کشورها، بااستفاده از هدف‌یابی‌های جغرافیایی ازپیش تعریف‌شده تعریف کنید. برای اطلاعات بیشتر، راه‌اندازی منطقه‌ها را ببینید.

Merchant API نقاط پایانی دسته‌ای برای مدیریت مناطق شما ارائه می‌دهد و به شما امکان می‌دهد تا ۱۰۰ منطقه را در یک فراخوانی API ایجاد، به‌روزرسانی، و حذف کنید. این روش برای فروشندگانی که قیمت‌گذاری و دسترسی منطقه‌ای (RAAP) را در مقیاس بزرگ مدیریت می‌کنند ایده‌آل است، زیرا کارایی را بهبود می‌بخشد و ادغام را ساده‌تر می‌کند.

نمای کلی

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

نمونه زیر نحوه ایجاد چند منطقه را در درخواست دسته‌ای نشان می‌دهد:

جاوا

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 ارائه دهید.

درخواست

نشانی وب درخواست را به‌صورت زیر بسازید:

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

نمونه زیر نحوه به‌روزرسانی چندین منطقه را در یک درخواست دسته‌ای نشان می‌دهد:

جاوا

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

محدودیت‌ها

قبل‌از شروع، این قوانین را به‌خاطر داشته باشید:

  • عملیات اتمی: درخواست‌های دسته‌ای اتمی هستند. اگر هریک از عملیات‌ها در دسته ناموفق باشد (برای مثال، یک منطقه ایجاد نشود)، کل دسته ناموفق خواهد بود و هیچ تغییری اعمال نخواهد شد. میانای برنامه‌سازی کاربردی خطایی را برمی‌گرداند که علت عدم موفقیت را به‌تفصیل شرح می‌دهد.
  • محدودیت‌های دسته‌ای: هر درخواست دسته‌ای می‌تواند شامل حداکثر ۱۰۰ عملیات منطقه‌ای باشد.
  • سهمیه‌ها: این نقاط پایانی از همان گروه‌های سهمیه همتایان تک‌عملیاتی خود (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"
}

برای رفع این مشکل، قبل‌از ارسال درخواست، درستی‌سنجی کنید که همه مناطقی که می‌خواهید به‌روزرسانی کنید وجود داشته باشند.