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

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

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

نمای کلی

«میانای برنامه‌سازی کاربردی دسته‌ای» به شما امکان می‌دهد کارهای زیر را با روش‌های مرتبط انجام دهید:

  • ایجاد چندین منطقه در یک درخواست: regions:batchCreate
  • حذف چند منطقه به‌طور هم‌زمان: regions:batchDelete
  • به‌طور هم‌زمان چند منطقه را به‌روز کنید: regions:batchUpdate

پیش‌نیازها

همه درخواست‌های دسته‌ای برای اصالت‌سنجی به نقش کاربر سرپرست نیاز دارند.

ایجاد چندین منطقه

این مثال نشان می‌دهد چگونه در یک تماس 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 باید حاوی شناسه منطقه‌ای باشد که باید به‌روز شود، برای مثال، «۹۸۰۰۵». منبع را به‌صورت 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);
  }
}

محدودیت‌ها

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

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

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