עדכון מלאי בחנויות מקומיות ל-AI Commerce Search

‫LocalInventory הוא מידע על מלאי שטחים פרסומיים שמשויך למקום מסוים, שמזוהה באמצעות place_id. לדוגמה, אפשר ליצור LocalInventory לחנות או לאזור שבהם מחיר מסוים זמין. ‫LocalInventory כולל את השדות הבאים:

  • LocalInventory.price_info
  • LocalInventory.attributes
  • LocalInventory.fulfillment_types

רשומות קיימות של LocalInventory מוצגות דרך Product.local_inventories (למעט fulfillment_types, שזמין דרך Product.fulfillment_info לצורך תאימות לדורות קודמים). השדה הזה הוא פלט בלבד. ההגדרה Product.local_inventories עבור Product ממשקי API של CRUD או SetInventory לא משפיעה.

כל זוג (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) מצביע על אותו זוג (fulfillment_info.place_ids, fulfillment_info.type) שמוזכר במסמכי העזרה בנושא עדכון מלאי שטחי הפרסום. fulfillment_types updated by AddLocalInventories and RemoveLocalInventories reflects a mapping from each place ID to a list of fulfillment types it supports, while fulfillment_info updated by AddFulfillmentPlaces and RemoveFulfillmentPlaces reflects a mapping from each specific fulfillment type to a list of place IDs that supports such type. עם זאת, שני סוגי ממשקי ה-API משנים את אותם נתוני מימוש בסיסיים, וההשפעה של שני סוגי ממשקי ה-API תבוא לידי ביטוי ב-Product.fulfillment_info.

שיטות לעדכון מלאי בחנויות מקומיות

שינויים בפרטי המלאי של מוצר בחנות מקומית יכולים לקרות הרבה יותר פעמים מאשר שינויים בפרטי המוצר בקטלוג. יש קבוצה מיוחדת של שיטות שנועדו לטפל בעדכונים של כמויות גדולות של נתוני מלאי בחנות מקומית. השיטות האלה הן אסינכרוניות בגלל אופטימיזציות במורד הזרם שתומכות במאות עדכונים בו-זמנית לכל מוצר, בלי לפגוע בביצועים.

AddLocalInventories

אפשר להשתמש ב-AddLocalInventories כדי ליצור מלאי של חנויות מקומיות במקומות חדשים (שמיוצגים באמצעות place_id חדשים), או לעדכן שדות קיימים במלאי קיים של חנויות מקומיות. אפשר לציין שדות שנוספו או עודכנו ברשימת הערכים LocalInventory בגוף הבקשה באמצעות AddLocalInventoriesRequest.add_mask. הערכים התקינים של add_mask הם:

  • ‫price_info: מחליף את LocalInventory.price_info.
  • attributes: מחליף את כל LocalInventory.attributes. מאפיינים קיימים שלא מוזכרים בגוף הבקשה יוסרו.
  • ‫attributes.PLACEHOLDER_NAME: מחליף רק את המאפיין המותאם אישית שצוין. אם לא מציינים שם מאפיין קיים בבקשה, המאפיין נמחק. אפשר לציין כמה מאפיינים attributes.PLACEHOLDER_NAME, כל עוד כל שם מאפיין שונה. עם זאת, אי אפשר לכלול בבקשה אחת את הערך attributes ואת הערכים attributes.PLACEHOLDER_NAME.AddLocalInventoriesRequest.add_mask
  • ‫fulfillment_types: מחליף את כל סוגי המימוש הנתמכים. סוגי מימוש קיימים שלא מוזכרים בגוף הבקשה יוסרו.

Proto

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store1"
    price_info: {
      currency_code: "USD"
      price: 100
      original_price: 110
      cost: 95
    }
    fulfillment_types: "pickup-in-store"
    fulfillment_types: "ship-to-store"
  }
  local_inventories: {
    place_id: "store2"
    price_info: {
      currency_code: "USD"
      price: 200
      original_price: 210
      cost: 195
    }
    attributes: {
      key: "attr1",
      value: {
        text: "store2_value"
      }
    }
    fulfillment_types: "custom-type-1"
  }
  add_mask: {
    paths: "price_info"
    paths: "attributes.attr1"
    paths: "fulfillment_types"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}

בדוגמה הזו AddLocalInventoriesRequest נוספים או מתעדכנים שני מלאים בחנויות מקומיות עם מזהי מקום "store1" ו-"store2" למוצר שצוין. אם store1 קיים ו-store2 לא קיים לפני הבקשה, הבקשה תעדכן את השדות של store1 ותיצור את store2 עם ערכי השדות שצוינו.

המאפיין AddLocalInventoriesRequest.add_mask מציין שצריך לעדכן את price_info, מאפיין מותאם אישית יחיד עם השם "attr1", ואת fulfillment_types באמצעות הערכים שצוינו ב-AddLocalInventoriesRequest.local_inventories.

‫attributes הם מאפיינים שמשויכים למקום עם שם וערכים שניתנים להתאמה אישית. מכיוון ש-LocalInventory של store1 לא מספק את הערך של attr1 בבקשה, מאפיין מותאם אישית attr1 יימחק מ-LocalInventory הקיים של store1 אם הוא קיים. הערך של המאפיין attr1 של store2 יוגדר כערך הטקסט store2_value. מאפיינים קיימים אחרים בהתאמה אישית ב-store1 וב-store2 לא מושפעים.

‫fulfillment_types מייצג רשימה של זמינות אספקה עבור Product במקום אחד. היא זהה לפונקציה fulfillment_info.type ומקבלת את אותם ערכים. הערך AddLocalInventoriesRequest מציין שstore1 תומך בסוגי ההפצה pickup-in-store ו-ship-to-store, וstore1 תומך ב-custom-type-1. סוגי מימוש שהיו קיימים לפני העדכון הזה ולא מוזכרים בבקשה יימחקו.

מכיוון שהערך של AddLocalInventoriesRequest.allow_missing הוא true, גם אם המוצר עדיין לא קיים, נתוני המלאי המעודכנים בחנות המקומית יישמרו עד ליצירת המוצר. העדכון מתבצע עם חותמת זמן AddLocalInventoriesRequest.add_time כדי למנוע מצב שבו עדכונים ישנים יחליפו את השדות שצוינו של מזהי המקומות האלה. מידע נוסף על מניעת עדכונים לא עדכניים ועל אחסון של נתוני מלאי בחנויות מקומיות לפני יצירת המוצר זמין במאמרים הגנות על חותמות זמן בעדכוני מלאי בחנויות מקומיות וטעינה מראש של נתוני מלאי.

Proto

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store3"
    attributes: {
      key: "attr1",
      value: {
        text: "attr1_value"
      }
    }
    attributes: {
      key: "attr2",
      value: {
        numbers: 123
      }
    }
  }
  add_mask: {
    paths: "attributes"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
}

בדוגמה הזו AddLocalInventoriesRequest נוסף או מתעדכן מלאי מקומי יחיד עם מזהה מקום "store3" למוצר שצוין. מכיוון שהמאפיין add_mask מכיל את הערך "attributes", כל המאפיינים המותאמים אישית הקיימים של store3 נמחקים ומוחלפים במאפיינים attr1 ו-attr2 כפי שצוין בבקשה. שימו לב: מכיוון שלא מוגדר allow_missing, המוצר שצוין חייב להתקיים. אחרת, מוצגת שגיאת NOT_FOUND.

RemoveLocalInventories

אפשר להשתמש ב-RemoveLocalInventories כדי להסיר מלאי קיים של חנויות מקומיות במקומות עם מזהי מקומות נתונים.

Proto

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  place_ids: "store1"
  place_ids: "store2"
  remove_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}

בדוגמה הזו RemoveLocalInventoriesRequest מסירים את נתוני המלאי בחנויות מקומיות עבור מקומות עם מזהי מקום "store1" ו-"store2" למוצר שצוין. העדכון מוטבע בחותמת זמן עם RemoveLocalInventoriesRequest.remove_time כדי למנוע מעדכונים ישנים לבטל את המחיקה של מזהי המקומות האלה. למזהי מקומות שצוינו ושאין להם נתוני מלאי מקומיים קיימים, הבקשה גם מתעדת את זמן העדכון שלהם כ-remove_time. מידע נוסף על חותמות זמן של עדכונים זמין במאמר בנושא אמצעי הגנה על חותמות זמן של עדכוני מלאי בחנויות מקומיות

הגנות על חותמות זמן בעדכוני מלאי של חנויות מקומיות

כדי להגן מפני עדכונים לא מסודרים, כל שדה של מלאי בחנות מקומית משויך לזמן העדכון האחרון.

שעת העדכון האחרון מתועדת לכל צמד של (place_id, price_info),‏ (place_id, attributes[...]) ו(place_id, fulfillment_types[...]).

השיטות AddLocalInventories ו-RemoveLocalInventories מאפשרות למבצע הקריאה לציין זמן עדכון לבקשה. העדכון יתבצע רק אם השעה שבה הוא בוצע מאוחרת מהשעה שבה בוצע העדכון האחרון.

לדוגמה, נניח שמזהה המקום "store1" כולל את הערך price_info, ומועד העדכון האחרון שתועד מוגדר לשעה T. אם RemoveLocalInventoriesRequest.place_ids מכיל "store1", הבקשה תסיר את price_info מ-"store1" רק אם RemoveLocalInventoriesRequest.remove_time מאוחר יותר מהזמן T. אותו עיקרון חל על RemoveLocalInventoriesRequest.

במסגרת ההגנה על חותמות זמן, יכול להיות ש-RemoveLocalInventoriesRequest יסיר רק שדות מסוימים של LocalInventory ולא את כולם. נניח שיש מלאי של מוצרים בחנות מקומית עם מזהה מקום "store1", שיש לו price_info עם זמן העדכון האחרון שתועד שמוגדר לזמן T1, ושיש לו מאפיין מותאם אישית קיים יחיד בשם "attr1" עם זמן העדכון האחרון שתועד שמוגדר לזמן T2. אם RemoveLocalInventoriesRequest.place_ids מכיל את "store1", והמאפיין remove_time מוגדר לערך T3 (כאשר T1 < T3 < T2), המאפיין price_info של store_1 יוסר, אבל המאפיין attr1 שלו לא ישתנה.

טעינה מראש של פרטי מלאי

כל אחת משיטות העדכון של המלאי בחנות מקומית מאפשרת למתקשר להגדיר את allow_missing בבקשה. אם הערך של allow_missing מוגדר כ-true, עדכון של מלאי בחנות מקומית שמתייחס ל-Product שלא קיים יעובד כאילו Product קיים, בהתאם למפרט השיטה. המידע על מלאי בחנויות מקומיות יישמר למשך יומיים לכל היותר אם Productהקובץ המתאיםCreateProduct לא ייווצר באמצעות CreateProduct בפרק הזמן הזה.