المناطق

تسمح لك خدمة regions بإنشاء وإدارة المناطق الجغرافية التي يمكنك استخدامها كأهداف مع كلٍ من regionalinventory وshippingsettings يمكنك تحديد المناطق كمجموعات من الرموز البريدية أو بعض البلدان، وذلك باستخدام geotargets. يوفّر هذا الدليل أمثلة على كيفية تحديد كل نوع من المناطق، بالإضافة إلى كيفية إنشاء نموذج إلغاء السعر: للحصول على معلومات إضافية عن خدمة "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 التالي والطلب. body:

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)، قد تصل بسرعة إلى الحد الأقصى لمساحة التخزين. وفي هذه الحالة، يكون الحل البديل لإدارة regions وshippingsettings على مستوى معرّف التاجر. لا يوجد لزيادة حصة المناطق إلى ما هو أبعد من الحد الأقصى البالغ 2 ميغابايت.

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

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

لإنشاء المنطقة، يمكنك تقديم طلب POST باستخدام عنوان URL التالي ثم إرسال طلب. body:

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