المناطق

تتيح لك خدمة regions إنشاء وإدارة مناطق جغرافية يمكنك استخدامها كأهداف مع خدمتَي regionalinventory وshippingsettings معًا. يمكنك تحديد المناطق كمجموعات من الرموز البريدية أو في بعض البلدان باستخدام الأهداف الجغرافية المحدّدة مسبقًا. يقدّم هذا الدليل أمثلة على كيفية تحديد كل نوع من أنواع المناطق، بالإضافة إلى كيفية إلغاء السعر على مستوى منطقة معيّنة. للحصول على معلومات إضافية حول خدمة regions، بما في ذلك كل الطرق والمَعلمات المتاحة، يُرجى الاطّلاع على المستندات المرجعية.

الأهلية حسب المنطقة

عند إنشاء منطقة، تحدِّد خدمة المناطق ما إذا كان بإمكانك استخدام المنطقة مع خدمات Content API الأخرى. يتضمن كائن الاستجابة الذي يتم عرضه لاستدعاء regions.create ناجح حقلَين منطقيَين، وهما regionalInventoryEligible وshippingEligible، ويشيران إلى ما إذا كان بإمكانك استخدام المنطقة مع خدمتَي regionalinventory وshippingsettings على التوالي.

regionalInventoryEligible

لكي تكون المنطقة مؤهّلة للاستخدام مع خدمة regionalinventory، يجب أن تستوفي المعايير التالية:

  • ويجب أن يحتوي regionId، الذي تحدده عند إنشاء منطقة، على أرقام فقط وأن يحتوي على 6 أرقام على الأقل.
  • ويجب أن تستوفي المنطقة الحد الأدنى لمتطلبات الحجم الخاصة بالمنطقة الجغرافية وعدد السكان على الإنترنت.

shippingEligible

لكي تكون المنطقة مؤهّلة للاستخدام مع خدمة shippingsettings، يجب أن تستوفي المعايير التالية:

  • يجب تحديد المنطقة باستخدام الرموز البريدية.
  • يجب أن تكون المنطقة جزءًا من بلد تتوفّر فيه خدمة shippingsettings.

عيّنات

إليك نموذج رمز كامل يمكنك استخدامه لإنشاء منطقة جديدة في Java:

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

الحد الأقصى المسموح به لبيانات regions وshippingsettings لكل حساب على Merchant Center هو 2 ميغابايت. يتم نسخ إعدادات الشحن والمنطقة داخليًا من حساب متعدّد العملاء إلى جميع حساباته الفرعية، لذلك لحسابات العملاء المتعددة العملاء (MCA) الأكبر حجمًا، قد تصل بسرعة إلى الحدّ الأقصى لمساحة التخزين. في هذه الحالة، يتمثل الحل البديل في إدارة regions وshippingsettings على مستوى معرّف التاجر. ليست هناك طريقة لزيادة حصة المناطق إلى أكثر من 2 ميغابايت.

إنشاء منطقة باستخدام الأهداف الجغرافية

بالنسبة إلى المناطق في البرازيل وروسيا، يمكنك أيضًا استخدام طريقة regions.create لإنشاء منطقة محدّدة على أنّها مجموعة من الاستهدافات الجغرافية التي تشكّل مناطق جغرافية محدّدة مسبقًا. تشمل أمثلة أنواع الاستهداف الجغرافي البلدان والولايات والمدن والأحياء والمطارات. مع ذلك، لا تتوافق خدمة regions حاليًا إلا مع النوع "ولاية" في البرازيل والنوع "المنطقة" لروسيا. لتنزيل ملف csv بجميع معرّفات الاستهداف الجغرافي، بما في ذلك الأهداف الجغرافية التي يمكن استخدامها مع خدمة regions، يُرجى الاطّلاع على الأهداف الجغرافية. ينشئ المثال أدناه منطقة جديدة من خلال توفير معرّفات الاستهداف الجغرافي لثلاث ولايات برازيلية.

لإنشاء المنطقة، يُرجى تقديم طلب 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”
}