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 = numerical_field_value. במקרה של טריות, attributeValue = (time.now() - datetime_field_value).
interpolationType

enum (InterpolationType)

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

object (ControlPoint)

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

AttributeType

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

טיפוסים בני מנייה (enum)
ATTRIBUTE_TYPE_UNSPECIFIED סוג מאפיין לא מזוהה.
NUMERICAL הערך של השדה המספרי ישמש לעדכון דינמי של סכום ההגדלה. במקרה הזה, ערך המאפיין (ערך x) של נקודת הבקרה יהיה הערך בפועל של השדה המספרי שעבורו צוין boostAmount.
FRESHNESS בתרחיש השימוש של רעננות, ערך המאפיין יהיה משך הזמן שחלף בין השעה הנוכחית לבין התאריך בשדה התאריך והשעה שצוין. הערך צריך להיות בפורמט של ערך 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 שבו יש להגדיל את הניקוד אם הערך של attributeValue שווה לערך שצוין למעלה.

FilterAction

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

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

string

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

מסמכי תחביר נדרשים: 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

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

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