Method: projects.locations.collections.dataStores.servingConfigs.recommend

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

בקשת HTTP


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

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

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

פרמטרים
servingConfig

string

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

כשיוצרים מנוע המלצות, נוצרת גם הגדרת ברירת מחדל אחת להצגת מודעות. מזהה המנוע משמש כמזהה של הגדרת ברירת המחדל להצגת מודעות. לדוגמה, במנוע 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 אף פעם לא מחזיר Documents עם 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
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

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

הרשאות IAM

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

  • discoveryengine.servingConfigs.recommend

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