REST Resource: projects.locations.collections.dataStores.controls

משאב: בקרה

הגדרת התנהגות מותנית שתופעל במהלך הצגת המודעה. כדי שההגדרה תישקל בזמן הצגת המודעה, היא צריכה להיות מצורפת לServingConfig. הפעולות המותרות תלויות בSolutionType.

ייצוג JSON 
{
  "name": string,
  "displayName": string,
  "associatedServingConfigIds": [
    string
  ],
  "solutionType": enum (SolutionType),
  "useCases": [
    enum (SearchUseCase)
  ],
  "conditions": [
    {
      object (Condition)
    }
  ],

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "boostAction": {
    object (BoostAction)
  },
  "filterAction": {
    object (FilterAction)
  },
  "redirectAction": {
    object (RedirectAction)
  },
  "synonymsAction": {
    object (SynonymsAction)
  },
  "promoteAction": {
    object (PromoteAction)
  }
  // End of mutually exclusive fields.
}
שדות
name

string

אי אפשר לשנות. שם ייחודי מלא projects/*/locations/global/dataStore/*/controls/*
displayName

string

חובה. שם קריא לאנשים. המזהה שמשמש בתצוגות של ממשק המשתמש.

מחרוזת מקודדת ב-UTF-8. הגבלת האורך היא 128 תווים. אחרת, מוצגת שגיאה מסוג INVALID ARGUMENT.
associatedServingConfigIds[]

string

פלט בלבד. רשימה של כל המזהים של ServingConfig שהבקרה הזו מצורפת אליהם. יכולות לעבור עד 10 דקות מרגע שהשינויים יתבצעו ועד שהם יתעדכנו.
solutionType

enum (SolutionType)

חובה. אי אפשר לשנות. הפתרון שאליו שייך אמצעי הבקרה.

הערך צריך להיות תואם לקטגוריית הישויות (vertical) של המשאב. אחרת, מוצגת שגיאה מסוג INVALID ARGUMENT.
useCases[]

enum (SearchUseCase)

מציינת את תרחיש השימוש של אמצעי הבקרה. משפיע על שדות התנאים שאפשר להגדיר. ההגדרה חלה רק על SOLUTION_TYPE_SEARCH. בשלב הזה, אפשר להגדיר רק תרחיש שימוש אחד לכל אמצעי בקרה. חובה להגדיר את הערך הזה כש-solutionType הוא SolutionType.SOLUTION_TYPE_SEARCH.
conditions[]

object (Condition)

ההגדרה הזו קובעת מתי הפעולה המשויכת תופעל.

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

object (BoostAction)

הגדרה של אמצעי בקרה מסוג הגברה
filterAction

object (FilterAction)

הגדרה של אמצעי בקרה מסוג מסנן. לא אפשרי כרגע על ידי Recommendation
redirectAction

object (RedirectAction)

הגדרה של אמצעי בקרה מסוג הפניה אוטומטית.
synonymsAction

object (SynonymsAction)

התייחסות לקבוצת מונחים כמילים נרדפות.
promoteAction

object (PromoteAction)

קידום קישורים מסוימים על סמך שאילתות מוגדרות מראש להפעלת הקידום.
סוף השדות הבלעדיים.

BoostAction

משנה את סדר המוצרים ברשימה שמוחזרת.

ייצוג JSON 
{
  "boost": number,
  "filter": string,
  "dataStore": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "fixedBoost": number,
  "interpolationBoostSpec": {
    object (InterpolationBoostSpec)
  }
  // End of mutually exclusive fields.
}
שדות
boost
(deprecated)

number

עוצמת ההגברה, שצריכה להיות בטווח [‎-1, 1]. הגברה שלילית משמעותה הורדה בדרגה. ברירת המחדל היא 0.0 (ללא פעולה).
filter

string

חובה. מציינים את המוצרים שעליהם רוצים להחיל את הגדלת נפח התנועה.

אם לא מציינים מסנן, כל המוצרים יקבלו דחיפה (No-op). מסמכי תחביר: https://cloud.google.com/retail/docs/filter-and-order האורך המקסימלי הוא 5,000 תווים. אחרת, מוצגת שגיאה מסוג INVALID ARGUMENT.
dataStore

string

חובה. מציין את מאגר הנתונים שהמסמכים שלו יכולים לקבל דחיפה באמצעות הרכיב הזה. שם מלא של מאגר נתונים, לדוגמה: projects/123/locations/global/collections/default_collection/dataStores/default_data_store
מפרטים של הגדלת ערך קבוע או הגדלת דירוג מותאם אישית. בהמשך מפורטת רשימה של שדות שאי אפשר להשתמש בהם בו-זמנית. רק אחד מהשדות הבאים יוגדר בתשובה:
fixedBoost

number

זה שינוי אופציונלי. עוצמת ההגברה, שצריכה להיות בטווח [‎-1, 1]. הגברה שלילית משמעותה הורדה בדרגה. ברירת המחדל היא 0.0 (ללא פעולה).
interpolationBoostSpec

object (InterpolationBoostSpec)

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

InterpolationBoostSpec

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

ייצוג JSON 
{
  "fieldName": string,
  "attributeType": enum (AttributeType),
  "interpolationType": enum (InterpolationType),
  "controlPoints": [
    {
      object (ControlPoint)
    }
  ]
}
שדות
fieldName

string

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

enum (AttributeType)

זה שינוי אופציונלי. סוג המאפיין שמשמש לקביעת סכום ההגדלה. אפשר לגזור את ערך המאפיין מערך השדה של fieldName שצוין. במקרה של מספרי זה פשוט, כלומר attributeValue = numeric_field_value. במקרה של טריות, לעומת זאת, attributeValue = (time.now() - datetime_field_value).
interpolationType

enum (InterpolationType)

זה שינוי אופציונלי. סוג האינטרפולציה שיש להחיל כדי לחבר את נקודות הבקרה המפורטות להלן.
controlPoints[]

object (ControlPoint)

זה שינוי אופציונלי. נקודות הבקרה שמשמשות להגדרת העקומה. הפונקציה המונוטונית (מוגדרת באמצעות סוג האינטרפולציה לעיל) עוברת דרך נקודות הבקרה המפורטות כאן.

AttributeType

המאפיין(או הפונקציה) שעליו יחול הדירוג המותאם אישית.

טיפוסים בני מנייה (enum)
ATTRIBUTE_TYPE_UNSPECIFIED סוג מאפיין לא מזוהה.
NUMERICAL הערך של השדה המספרי ישמש לעדכון דינמי של כמות הדחיפה. במקרה הזה, ערך המאפיין (ערך x) של נקודת הבקרה יהיה הערך בפועל של השדה המספרי שעבורו צוין boostAmount.
FRESHNESS עבור מקרה השימוש של רעננות, ערך התכונה יהיה משך הזמן בין השעה הנוכחית לתאריך בשדה ה-datetime שצוין. הערך צריך להיות בפורמט של ערך XSD dayTimeDuration (קבוצת משנה מוגבלת של ערך משך זמן לפי תקן ISO 8601). הדוגמה לכך היא: [nD][T[nH][nM][nS]]. לדוגמה, 5D, ‏ 3DT12H30M, ‏ T24H.

InterpolationType

סוג האינטרפולציה שיש להחיל. ברירת המחדל תהיה לינארית (Piecewise Linear).

טיפוסים בני מנייה (enum)
INTERPOLATION_TYPE_UNSPECIFIED לא צוין סוג האינטרפולציה. במקרה כזה, ברירת המחדל היא לינארית.
LINEAR תופעל אינטרפולציה ליניארית מקטעית.

ControlPoint

נקודות הבקרה שמשמשות להגדרת העקומה. העקומה שמוגדרת באמצעות נקודות הבקרה האלה יכולה להיות רק עולה או יורדת(ערכים קבועים הם אפשריים).

ייצוג JSON 
{
  "attributeValue": string,
  "boostAmount": number
}
שדות
attributeValue

string

זה שינוי אופציונלי. יכול להיות אחד מהערכים הבאים: 1. הערך המספרי של השדה. 2. מפרט משך הזמן של הטריות: הערך חייב להיות בפורמט של ערך XSD dayTimeDuration (קבוצת משנה מוגבלת של ערך משך זמן בפורמט ISO 8601). הדוגמה לכך היא: [nD][T[nH][nM][nS]].
boostAmount

number

זה שינוי אופציונלי. הערך בין -1 ל-1 שבו יש להעלות את הציון אם ערך התכונה מוערך לערך שצוין לעיל.

FilterAction

הגדרתם אילו מוצרים יכולים להיכלל בתוצאות. משתמש באותו פילטר כמו בוסט.

ייצוג JSON 
{
  "filter": string,
  "dataStore": string
}
שדות
filter

string

חובה. מסנן שיוחל על תוצאות התנאים התואמים.

תיעוד תחביר נדרש: https://cloud.google.com/retail/docs/filter-and-order אורך מקסימלי הוא 5000 תווים. אחרת, מוצגת שגיאה מסוג INVALID ARGUMENT.
dataStore

string

חובה. מציין אילו מסמכים של מאגר נתונים ניתנים לסינון על ידי פקד זה. שם מלא של מאגר נתונים, לדוגמה: projects/123/locations/global/collections/default_collection/dataStores/default_data_store

RedirectAction

מפנה קונה לכתובת ה-URI שצוינה.

ייצוג JSON 
{
  "redirectUri": string
}
שדות
redirectUri

string

חובה. ה-URI שאליו יופנה הקונה.

חובה. אורך ה-URI צריך להיות 2,000 תווים או פחות. אחרת, מוצגת שגיאה מסוג INVALID ARGUMENT.

SynonymsAction

יוצרת קבוצה של מונחים שישמשו כמילים נרדפות.

לדוגמה, המילה happy תיחשב גם כ-glad, והמילה glad תיחשב גם כ-happy.

ייצוג JSON 
{
  "synonyms": [
    string
  ]
}
שדות
synonyms[]

string

מגדיר קבוצה של מילים נרדפות. אפשר לציין עד 100 מילים נרדפות. צריך לציין לפחות 2 מילים נרדפות. אחרת, מוצגת שגיאה מסוג INVALID ARGUMENT.

PromoteAction

לקדם קישורים מסוימים על סמך שאילתות טריגר מסוימות.

דוגמה: קידום קישור לחנות נעליים כשמחפשים את מילת המפתח shoe. הקישור יכול להיות מחוץ למאגר הנתונים המשויך.

ייצוג JSON 
{
  "dataStore": string,
  "searchLinkPromotion": {
    object (SearchLinkPromotion)
  }
}
שדות
dataStore

string

חובה. מאגר הנתונים שאליו המבצע הזה משויך.

SearchLinkPromotion

פרוטוקול הקידום כולל URI ומידע מועיל אחר להצגת הקידום.

ייצוג JSON 
{
  "title": string,
  "uri": string,
  "document": string,
  "imageUri": string,
  "description": string,
  "enabled": boolean
}
שדות
title

string

חובה. שם המבצע. האורך המקסימלי הוא 160 תווים.
uri

string

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

string

זה שינוי אופציונלי. ה-Document שהמשתמש רוצה לקדם. עבור חיפוש באתר, השאר את הערך ללא הגדרה ומלא רק את ה-URI. אפשר להגדיר אותו יחד עם uri.
imageUri

string

זה שינוי אופציונלי. כתובת ה-URL של התמונה הממוזערת של מבצע.
description

string

זה שינוי אופציונלי. תיאור המבצע. האורך המקסימלי הוא 200 תווים.
enabled

boolean

זה שינוי אופציונלי. קידום המכירות המופעל יוחזר לכל הגדרות ההצגה שמשויכות לרכיב ההורה של אמצעי הבקרה שאליו מצורף קידום המכירות הזה.

הדגל הזה משמש רק לחיפוש בסיסי באתר.

SearchUseCase

מגדיר תת-חלוקה נוספת של SolutionType. חל באופן ספציפי על SOLUTION_TYPE_SEARCH.

טיפוסים בני מנייה (enum)
SEARCH_USE_CASE_UNSPECIFIED ערך המשמש כאשר אינו מוגדר. לא יקרה ב-CSS.
SEARCH_USE_CASE_BROWSE עיון בתרחיש שימוש. התנועה צריכה לכלול query ריק.

תנאי

הגדרה של נסיבות שצריך לבדוק לפני שמאפשרים התנהגות מסוימת

ייצוג JSON 
{
  "queryTerms": [
    {
      object (QueryTerm)
    }
  ],
  "activeTimeRange": [
    {
      object (TimeRange)
    }
  ],
  "queryRegex": string
}
שדות
queryTerms[]

object (QueryTerm)

חיפוש רק ברשימה של מונחים שתואמים לשאילתה. אי אפשר להגדיר את הערך הזה אם הערך של Condition.query_regex מוגדר.

אפשר להשתמש בעד 10 מונחי שאילתה.
activeTimeRange[]

object (TimeRange)

טווח הזמן שבו התנאי פעיל.

אפשר להוסיף עד 10 טווחי זמן.
queryRegex

string

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

QueryTerm

התאמה לשאילתה של בקשה לחיפוש

ייצוג JSON 
{
  "value": string,
  "fullMatch": boolean
}
שדות
value

string

הערך הספציפי של השאילתה שצריך להתאים

חייב להיות באותיות קטנות, חייב להיות UTF-8. יכולים להכיל לכל היותר 3 איברים מופרדים ברווחים אם fullMatch הוא true. לא יכול להיות מחרוזת ריקה. אורך מקסימלי של 5,000 תווים.
fullMatch

boolean

האם שאילתת החיפוש צריכה להתאים במדויק למונח השאילתה.

TimeRange

משמש לתנאים תלויי זמן.

ייצוג JSON 
{
  "startTime": string,
  "endTime": string
}
שדות
startTime

string (Timestamp format)

תחילת טווח זמן.

הטווח כולל.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

סוף טווח התאריכים.

הטווח כולל. התאריך חייב להיות בעתיד.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

Methods

create

 יצירת אמצעי בקרה.

delete

 מחיקת אמצעי בקרה.

get

 מקבלים אמצעי בקרה.

list

 מפרט את כל אמצעי הבקרה לפי ההורה שלהם DataStore.

patch

 עדכון של אמצעי בקרה.