Method: projects.locations.dataStores.servingConfigs.recommend

נותן המלצה, שדורשת אירוע משתמש הקשרי.

בקשת HTTP

POST https://discoveryengine.googleapis.com/v1beta/{servingConfig=projects/*/locations/*/dataStores/*/servingConfigs/*}:recommend

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
servingConfig

string

חובה. שם המשאב המלא של ServingConfig: ‏ projects/*/locations/global/collections/*/engines/*/servingConfigs/* או projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

כשיוצרים מנוע המלצות, נוצרת גם הגדרת ברירת מחדל אחת להצגת מודעות. מזהה המנוע משמש כמזהה של הגדרת ברירת המחדל להצגת מודעות. לדוגמה, ב-Engine projects/*/locations/global/collections/*/engines/my-engine, אפשר להשתמש ב-projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine לבקשות RecommendationService.Recommend.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
שדות
userEvent

object (UserEvent)

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

אל תגדירו את UserEvent.user_pseudo_id או UserEvent.user_info.user_id לאותו מזהה קבוע עבור משתמשים שונים. אם אתם מנסים לקבל המלצות לא מותאמות אישית (לא מומלץ, כי זה עלול להשפיע לרעה על ביצועי המודל), במקום זאת צריך להגדיר את UserEvent.user_pseudo_id למזהה ייחודי אקראי ולהשאיר את UserEvent.user_info.user_id ללא הגדרה.
pageSize

integer

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

string

מסנן להגבלת תוצאות ההמלצות. אורך המסנן מוגבל ל-5,000 תווים. בשלב הזה יש תמיכה רק בביטויי סינון במאפיין filterTags.

דוגמאות:

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

אם הערך של attributeFilteringSyntax מוגדר כ-True בשדה params, המערכת מצפה לביטויים מבוססי-מאפיינים במקום לתחביר מבוסס-תגים שמתואר למעלה. דוגמאות:

  • ‫(language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • ‫(available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

אם המסנן חוסם את כל התוצאות, ה-API מחזיר מסמכים פופולריים כלליים (לא מסוננים). אם רוצים לקבל רק תוצאות שתואמות בדיוק למסננים, צריך להגדיר את strictFiltering לערך true ב-RecommendRequest.params כדי לקבל במקום זאת תוצאות ריקות.

הערה: ה-API אף פעם לא מחזיר Document עם storageStatus בתור EXPIRED או DELETED, בלי קשר לבחירות המסנן.
validateOnly

boolean

השתמשו במצב אימות בלבד לשאילתת ההמלצה הזו. אם הערך מוגדר כ-true, נעשה שימוש במודל מזויף שמחזיר מזהי מסמכים שרירותיים. שימו לב: צריך להשתמש במצב אימות בלבד רק כדי לבדוק את ה-API, או אם המודל לא מוכן.
params

map (key: string, value: value (Value format))

פרמטרים נוספים שספציפיים לדומיין להמלצות.

ערכים מותרים:

  • ‫returnDocument: בוליאני. אם הערך הוא true, אובייקט המסמך המשויך מוחזר ב-RecommendResponse.RecommendationResult.document.
  • ‫returnScore: בוליאני. אם הערך הוא true, ציון ההמלצה שמתאים לכל מסמך שמוחזר מוגדר ב-RecommendResponse.RecommendationResult.metadata. הציון שמוצג מציין את ההסתברות להמרה של מסמך בהינתן ההקשר וההיסטוריה של המשתמש.
  • ‫strictFiltering: בוליאני. ברירת המחדל היא True. אם הערך הוא false, השירות מחזיר מסמכים פופולריים כלליים (לא מסוננים) במקום מסמכים ריקים, אם המסנן חוסם את כל תוצאות ההמלצות.
  • ‫diversityLevel: מחרוזת. ברירת המחדל היא ריק. אם המדיניות מוגדרת כלא ריקה, צריך להגדיר בה אחד מהערכים הבאים:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity ההגדרה הזו מאפשרת שליטה ברמת הבקשה ומשנה את תוצאות ההמלצות על סמך קטגוריית המסמך.
  • ‫attributeFilteringSyntax: בוליאני. ברירת המחדל היא False. אם הערך הוא true, השדה filter יפורש בהתאם לתחביר החדש שמבוסס על מאפיינים.
userLabels

map (key: string, value: string)

התוויות של המשתמש שמוחלות על משאב צריכות לעמוד בדרישות הבאות:

  • אפשר להוסיף לכל משאב כמה תוויות, עד 64 לכל היותר.
  • כל תווית צריכה להיות צמד מפתח/ערך.
  • האורך המינימלי של המפתחות הוא תו אחד, והאורך המקסימלי הוא 63 תווים. המפתחות לא יכולים להיות ריקים. הערכים יכולים להיות ריקים, והאורך המקסימלי שלהם הוא 63 תווים.
  • המפתחות והערכים יכולים להכיל רק אותיות קטנות, ספרות, קווים תחתונים ומקפים. כל התווים צריכים להיות בקידוד UTF-8, ומותר להשתמש בתווים בינלאומיים.
  • החלק של המפתח בתווית חייב להיות ייחודי. עם זאת, אפשר להשתמש באותו מפתח עם כמה משאבים.
  • המפתחות צריכים להתחיל באות קטנה או בתו בינלאומי.

פרטים נוספים מופיעים במאמר דרישות לגבי תוויות.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של RecommendResponse.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite

ניתן למצוא מידע נוסף כאן: Authentication Overview.

הרשאות IAM

נדרשת הרשאת IAM הבאה במשאב servingConfig:

  • discoveryengine.servingConfigs.recommend

מידע נוסף מופיע במאמרי העזרה בנושא IAM.