אזורים

באמצעות השירות 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*"
      }
    ]
   }
}

יש מגבלה קשיחה של 2MB לנתונים ל-regions ול-shippingsettings לכל חשבון Merchant Center. הגדרות המשלוח והאזורים מועתקות באופן פנימי מחשבון MCA לכל חשבונות המשנה שלו, כך שבמקרה של חשבונות MCA גדולים, יכול להיות שתמצה במהירות את מגבלת האחסון. במקרה כזה, הדרך לעקוף את הבעיה היא לנהל את regions ואת shippingsettings ברמת מספר המזהה של המוכר. אין דרך להגדיל את מכסת האזורים מעבר למגבלה של 2MB.

יצירת אזור באמצעות טירגוטים גיאוגרפיים

לאזורים בברזיל וברוסיה אפשר גם להשתמש בשיטה 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”
}