مناطق

سرویس regions به شما امکان می دهد مناطق جغرافیایی را ایجاد و مدیریت کنید که می توانید از آنها به عنوان هدف با خدمات regionalinventory و shippingsettings استفاده کنید. می‌توانید مناطق را به‌عنوان مجموعه‌ای از کدهای پستی یا در برخی کشورها با استفاده از اهداف جغرافیایی از پیش تعریف‌شده تعریف کنید. این راهنما مثال هایی از نحوه تعریف هر نوع منطقه و همچنین نحوه ایجاد یک نادیده گرفتن قیمت منطقه ای ارائه می دهد. برای اطلاعات بیشتر در مورد سرویس regions ، از جمله تمام روش ها و پارامترهای موجود، به مستندات مرجع مراجعه کنید.

واجد شرایط بودن منطقه

وقتی منطقه ای ایجاد می کنید، سرویس مناطق تعیین می کند که آیا می توانید از این منطقه با سایر سرویس های Content API استفاده کنید یا خیر. شیء پاسخی که برای یک تماس موفق regions.create برگردانده می‌شود شامل دو فیلد منطقی، regionalInventoryEligible و shippingEligible است که نشان می‌دهد به ترتیب می‌توانید از منطقه با خدمات regionalinventory و shippingsettings استفاده کنید یا خیر.

regionalInventoryEligible

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

  • regionId که هنگام ایجاد یک منطقه مشخص می‌کنید، باید فقط شامل اعداد باشد و حداقل باید شامل 6 رقم باشد.
  • منطقه باید حداقل الزامات اندازه برای منطقه جغرافیایی و جمعیت آنلاین را برآورده کند.

حمل و نقل واجد شرایط

برای واجد شرایط بودن برای استفاده با سرویس shippingsettings ، یک منطقه باید معیارهای زیر را داشته باشد:

  • منطقه باید با استفاده از کد پستی تعریف شود.
  • منطقه باید بخشی از کشوری باشد که توسط سرویس shippingsettings پشتیبانی می شود.

نمونه ها

در اینجا یک نمونه کد کامل وجود دارد که می توانید از آن برای ایجاد یک منطقه جدید در جاوا استفاده کنید:

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package shopping.content.v2_1.samples.regions;

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.services.content.model.Region;
import com.google.api.services.content.model.RegionPostalCodeArea;
import com.google.api.services.content.model.RegionPostalCodeAreaPostalCodeRange;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import shopping.content.v2_1.samples.ContentSample;

/**
 * Creates a region. The region created here can be used with the regional inventory service.
 * Regional availability and pricing lets you provide product availability and variable pricing
 * based on your business presence and the location of your customer base. Regional availability and
 * pricing is available for products advertised through Shopping ads on Google Search, and listed in
 * free listings on the Shopping tab.
 */
public class RegionCreateSample extends ContentSample {
  public RegionCreateSample(String[] args) throws IOException {
    super(args);
  }

  @Override
  public void execute() throws IOException {
    checkNonMCA();

    // Creates a List of Postal Code Area Postal Code Ranges.
    // This allows you to flexibly define regions as combinations of postal code
    // ranges. Each postal code range in the list has its own start and end zip code.
    List<RegionPostalCodeAreaPostalCodeRange> postalCodeRanges =
        new ArrayList<RegionPostalCodeAreaPostalCodeRange>();

    // Creates a new postal code range from two postal code values.
    // This range is equivalent to all postal codes in the USA state of New York (00501 - 14925)
    RegionPostalCodeAreaPostalCodeRange postalCodeRange =
        new RegionPostalCodeAreaPostalCodeRange().setBegin("00501").setEnd("14925");

    // Adds the NY State postal code range into the list of postal code ranges that a postal
    // code area accepts.
    postalCodeRanges.add(postalCodeRange);

    // Creates Postal Code Area for the Region that will be inserted, using the NY State postal code
    // ranges, and the US CLDR territory/country code that the postal code ranges applies to.
    RegionPostalCodeArea postalCodeArea =
        new RegionPostalCodeArea().setPostalCodes(postalCodeRanges).setRegionCode("US");

    // Creates a region with example values for displayName and postalCodeArea
    Region region = new Region().setDisplayName("NYState").setPostalCodeArea(postalCodeArea);

    // Tries to create the region, and catches any exceptions
    try {
      System.out.println("Creating region");
      Region result =
          content
              .regions()
              .create(this.config.getMerchantId().longValue(), region)
              .setRegionId("12345678") // User-defined, numeric, minimum of 6 digits
              .execute();
      System.out.println("Listing succesfully created region");
      System.out.println(result);
    } catch (GoogleJsonResponseException e) {
      checkGoogleJsonResponseException(e);
    }
  }

  public static void main(String[] args) throws IOException {
    new RegionCreateSample(args).execute();
  }
}

ایجاد یک منطقه با استفاده از کدهای پستی

می توانید از روش regions.create برای ایجاد منطقه ای که به عنوان مجموعه ای از کدهای پستی تعریف شده است استفاده کنید. مثال زیر با تعیین طیف وسیعی از کدهای پستی، منطقه جدیدی را برای ایالت آریزونا در ایالات متحده ایجاد می کند.

برای ایجاد منطقه، یک درخواست POST با URL و بدنه درخواست زیر ایجاد کنید:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=456789

{
  postalCodeArea: {
    regionCode: "US",
    postalCodes: [
      {
        begin: "850*",
        end: "860*"
      }
    ]
   }
}

محدودیت سخت 2 مگابایت داده برای regions و shippingsettings در هر حساب Merchant Center وجود دارد. تنظیمات حمل و نقل و منطقه به صورت داخلی از یک MCA در همه حساب‌های فرعی آن کپی می‌شوند، بنابراین برای MCA‌های بزرگ‌تر، ممکن است به سرعت به محدودیت فضای ذخیره‌سازی خود برسید. در این مورد، یک راه حل، مدیریت regions و shippingsettings در سطح شناسه تجاری است. هیچ راهی برای افزایش سهمیه مناطق خود از حد 2 مگابایت وجود ندارد.

ایجاد یک منطقه با استفاده از اهداف جغرافیایی

برای مناطقی در برزیل و روسیه، می‌توانید از روش regions.create برای ایجاد منطقه‌ای که به عنوان مجموعه‌ای از اهداف جغرافیایی تعریف شده است، استفاده کنید، که مناطق جغرافیایی از پیش تعریف شده هستند. نمونه‌هایی از انواع هدف‌های جغرافیایی شامل کشورها، ایالت‌ها، شهرها، محله‌ها و فرودگاه‌ها هستند. با این حال، سرویس regions در حال حاضر فقط از نوع "دولت" برای برزیل و نوع "منطقه" برای روسیه پشتیبانی می کند. برای دانلود یک فایل csv از تمام شناسه‌های geotarget، از جمله اهداف جغرافیایی که می‌توان با سرویس regions استفاده کرد، به Geotargets مراجعه کنید. مثال زیر با ارائه شناسه های هدف جغرافیایی سه ایالت برزیل، یک منطقه جدید ایجاد می کند.

برای ایجاد منطقه، یک درخواست POST با استفاده از URL و بدنه درخواست زیر ایجاد کنید:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/regions?regionId=123456

{
  geoTargetAreas: {
    geotargetCriteriaId: [20106, 20102, 20101] //Sao Paulo, Rio de Janeiro, Parana
  }
}

از مناطق برای ایجاد نادیده گرفتن قیمت منطقه ای استفاده کنید

هنگامی که یک منطقه ایجاد می کنید، سرویس regions یک شی پاسخ را برمی گرداند که شامل یک regionId و دو فیلد وضعیت واجد شرایط بودن است. اگر مقدار regionalInventoryEligible true باشد، می‌توانید از سرویس regionaliventory برای ایجاد یک لغو استفاده کنید که قیمت متفاوتی را برای منطقه تعیین می‌کند. مثال زیر با استفاده از منطقه مبتنی بر کد پستی ایجاد شده در مثال بالا، که دارای یک regionId "456789" است، یک نادیده گرفتن قیمت منطقه ای ایجاد می کند.

برای ایجاد لغو، یک درخواست POST با استفاده از URL و بدنه درخواست زیر ایجاد کنید:

https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/{productId}/regionalinventory

{
  “regionId”: "456789"
  “price”: {
    value: “10”
    currency: “USD”
  },
  “availability”: “in stock”
}