REST Resource: advertisers.insertionOrders

משאב: הזמנת קמפיין

הזמנת קמפיין אחת.

ייצוג ב-JSON 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "insertionOrderId": string,
  "displayName": string,
  "insertionOrderType": enum (InsertionOrderType),
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "partnerCosts": [
    {
      object (PartnerCost)
    }
  ],
  "pacing": {
    object (Pacing)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "integrationDetails": {
    object (IntegrationDetails)
  },
  "kpi": {
    object (Kpi)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "optimizationObjective": enum (OptimizationObjective)
}
שדות
name

string

פלט בלבד. שם המשאב של הזמנת ההצגה.
advertiserId

string (int64 format)

פלט בלבד. המזהה הייחודי של המפרסם שההזמנה שייכת אליו.
campaignId

string (int64 format)

חובה. לא ניתן לשינוי. המזהה הייחודי של הקמפיין שאליו שייך הזמנת ההצגה.
insertionOrderId

string (int64 format)

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

string

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

הקידוד חייב להיות UTF-8 והגודל המקסימלי הוא 240 בייטים.
insertionOrderType

enum (InsertionOrderType)

סוג הזמנת הקמפיין.

אם לא מציינים את השדה הזה בזמן היצירה, הערך שמוגדר כברירת מחדל הוא RTB.
entityStatus

enum (EntityStatus)

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

  • בשיטה insertionOrders.create, מותר להשתמש רק ב-ENTITY_STATUS_DRAFT. כדי להפעיל הזמנת קמפיין, משתמשים בשיטה insertionOrders.patch ומעדכנים את הסטטוס ל-ENTITY_STATUS_ACTIVE אחרי היצירה.
  • לא ניתן לשנות את הסטטוס של הזמנת קמפיין מסטטוס אחר לסטטוס ENTITY_STATUS_DRAFT.
  • לא ניתן להגדיר הזמנת קמפיין ל-ENTITY_STATUS_ACTIVE אם הקמפיין ההורה שלה לא פעיל.
updateTime

string (Timestamp format)

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

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

object (PartnerCost)

עלויות השותף שמשויכות לסדר ההכנסה.

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

object (Pacing)

חובה. הגדרת קצב ההוצאה של התקציב בסדר ההכנסה.

pacingType PACING_TYPE_ASAP לא תואם ל-pacingPeriod PACING_PERIOD_FLIGHT.
frequencyCap

object (FrequencyCap)

חובה. ההגדרה של מכסת התדירות של הזמנת ההצגה.
integrationDetails

object (IntegrationDetails)

פרטי שילוב נוספים של הזמנת הקמפיין.
kpi

object (Kpi)

חובה. מדד הביצועים המרכזי (KPI) של הזמנת הקמפיין.

המטרה הזו מכונה 'יעד' בממשק של Display & Video 360.
budget

object (InsertionOrderBudget)

חובה. הגדרות הקצאת התקציב של סדר ההכנסה.
bidStrategy

object (BiddingStrategy)

שיטת הבידינג של הזמנת ההצגה. כברירת מחדל, הערך fixedBid מוגדר.
reservationType

enum (ReservationType)

פלט בלבד. סוג ההזמנה של הזמנת הקמפיין.
optimizationObjective

enum (OptimizationObjective)

זה שינוי אופציונלי. יעד האופטימיזציה של סדר ההכנסה.

InsertionOrderType

סוגי ההזמנות האפשריים.

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

טיפוסים בני מנייה (enum)
INSERTION_ORDER_TYPE_UNSPECIFIED סוג הזמנת הקמפיין לא צוין או לא ידוע.
RTB בידינג בזמן אמת.
OVER_THE_TOP ישירות ללקוח.

KPI

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

ייצוג ב-JSON 
{
  "kpiType": enum (KpiType),
  "kpiAlgorithmId": string,

  // Union field kpi_value can be only one of the following:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of list of possible types for union field kpi_value.
}
שדות
kpiType

enum (KpiType)

חובה. סוג מדד ה-KPI.
kpiAlgorithmId

string (int64 format)

זה שינוי אופציונלי. מזהה של אלגוריתם בידינג מותאם אישית שמשויך ל-KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. המערכת תתעלם מהשדה הזה אם לא תבחרו את מדד ה-KPI המתאים.
שדה האיחוד kpi_value. חובה. הערך של מדד ה-KPI. השדה הרלוונטי תואם ל-kpi_type. הערך של kpi_value יכול להיות רק אחת מהאפשרויות הבאות:
kpiAmountMicros

string (int64 format)

סכום היעד, במיליוניות של המטבע של המפרסם.

רלוונטי כאשר kpiType הוא אחד מהערכים הבאים:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

לדוגמה: הערך 1500000 מייצג 1.5 יחידות סטנדרטיות של המטבע.
kpiPercentageMicros

string (int64 format)

הייצוג העשרוני של אחוז היעד ב-micros.

רלוונטי כאשר kpiType הוא אחד מהערכים הבאים:

  • KPI_TYPE_CTR
  • KPI_TYPE_VIEWABILITY
  • KPI_TYPE_CLICK_CVR
  • KPI_TYPE_IMPRESSION_CVR
  • KPI_TYPE_VTR
  • KPI_TYPE_AUDIO_COMPLETION_RATE
  • KPI_TYPE_VIDEO_COMPLETION_RATE

לדוגמה: הערך 70000 מייצג 7% (0.07 בערך עשרוני).
kpiString

string

מחרוזת של מדד KPI, שיכולה להיות ריקה. חייב להיות מקודד ב-UTF-8 באורך של עד 100 תווים.

רלוונטי כאשר הערך של kpiType הוא KPI_TYPE_OTHER.

KpiType

סוגי מדדי הביצועים המרכזיים (KPI) האפשריים.

טיפוסים בני מנייה (enum)
KPI_TYPE_UNSPECIFIED סוג מדד ה-KPI לא צוין או לא ידוע בגרסה הזו.
KPI_TYPE_CPM מדד ה-KPI הוא עלות לאלף חשיפות (CPM).
KPI_TYPE_CPC מדד ה-KPI הוא עלות לקליק (CPC).
KPI_TYPE_CPA מדד ה-KPI הוא עלות להמרה (CPA).
KPI_TYPE_CTR מדד ה-KPI הוא אחוז שיעור הקליקים (CTR).
KPI_TYPE_VIEWABILITY מדד ה-KPI הוא אחוז הניראות.
KPI_TYPE_CPIAVC מדד ה-KPI הוא עלות לחשיפת אודיו וחשיפה ויזואלית בעת ההשלמה (CPIAVC).
KPI_TYPE_CPE מדד ה-KPI הוא עלות לאינטראקציה ראשונית (CPE).
KPI_TYPE_CPV מדד ה-KPI מוגדר לפי עלות לצפייה (CPV).
KPI_TYPE_CLICK_CVR מדד ה-KPI הוא שיעור ההמרה מקליקים (המרות לקליק) באחוזים.
KPI_TYPE_IMPRESSION_CVR מדד ה-KPI הוא אחוז שיעור ההמרה לחשיפה (המרות לחשיפה).
KPI_TYPE_VCPM מדד ה-KPI הוא עלות לאלף חשיפות שניתנות לצפייה (vCPM).
KPI_TYPE_VTR מדד ה-KPI הוא אחוז שיעור הצפייה ב-YouTube (צפיות ב-YouTube לכל חשיפה).
KPI_TYPE_AUDIO_COMPLETION_RATE מדד ה-KPI הוא אחוז שיעור השלמת ההאזנה (האזנות שהושלמו למודעות אודיו לכל חשיפה).
KPI_TYPE_VIDEO_COMPLETION_RATE מדד ה-KPI הוא אחוז שיעור השלמת הצפייה בסרטון (צפיות שהושלמו בסרטון לכל חשיפה).
KPI_TYPE_CPCL מדד ה-KPI מוגדר לפי עלות להאזנה שהושלמה (CPCL).
KPI_TYPE_CPCV מדד ה-KPI מוגדר לפי עלות לצפייה שהושלמה בסרטון (CPCV).
KPI_TYPE_TOS10 מדד ה-KPI מוגדר לפי שיעור הזמן במסך 10 שניות או יותר (אחוז החשיפות המדידה שלא ניתנות לדילוג שהוצגו במסך למשך 10 שניות לפחות).
KPI_TYPE_MAXIMIZE_PACING מדד ה-KPI מוגדר למקסום ההשפעה על המותג תוך מתן עדיפות לניצול מלא של התקציב.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST מדד ה-KPI מוגדר כערך חשיפות בהתאמה אישית חלקי עלות.
KPI_TYPE_OTHER מדד ה-KPI הוא ערך אחר.

InsertionOrderBudget

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

ייצוג ב-JSON 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
שדות
budgetUnit

enum (BudgetUnit)

חובה. לא ניתן לשינוי. יחידת התקציב מציינת אם התקציב מבוסס על מטבע או על חשיפות.
automationType

enum (InsertionOrderAutomationType)

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

אם לא מציינים את השדה הזה בזמן היצירה, הערך שמוגדר כברירת מחדל הוא INSERTION_ORDER_AUTOMATION_TYPE_NONE.
budgetSegments[]

object (InsertionOrderBudgetSegment)

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

InsertionOrderAutomationType

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

טיפוסים בני מנייה (enum)
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED אפשרות האוטומציה של הזמנת ההצגה לא צוינה או לא מוכרת בגרסה הזו.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET הקצאת תקציב אוטומטית. מאפשרים למערכת להעביר באופן אוטומטי את התקציב לפריטי העלויות שבבעלותם, כדי לבצע אופטימיזציה של הביצועים שמוגדרים לפי kpi. אין אוטומציה בהגדרות של הצעות המחיר.
INSERTION_ORDER_AUTOMATION_TYPE_NONE אין אוטומציה של הצעות מחיר או תקציבים ברמת סדר ההכנסה. צריך להגדיר את הצעת המחיר והתקציב באופן ידני ברמת הפריט.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET מאפשרים למערכת לשנות באופן אוטומטי את הצעות המחיר ולהעביר את התקציב לפריטי העלויות שבבעלותם, כדי לבצע אופטימיזציה של הביצועים שמוגדרים על ידי kpi.

InsertionOrderBudgetSegment

הגדרות ששולטות בתקציב של מקטע תקציב יחיד.

ייצוג ב-JSON 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
שדות
budgetAmountMicros

string (int64 format)

חובה. סכום התקציב שיופעל בסדר ההכנסה עבור dateRange הנתון. הסכום מופיע במיליוניות. הערך חייב להיות גדול מ-0. לדוגמה, הערך 500000000 מייצג 500 יחידות רגילות של המטבע.
description

string

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

הקידוד חייב להיות UTF-8.
dateRange

object (DateRange)

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

  • כשיוצרים פלח תקציב חדש, הערכים של startDate ו-endDate חייבים להיות בעתיד.
  • לפלח תקציב קיים עם startDate בעבר יש endDate שניתן לשינוי, אבל startDate שלא ניתן לשינוי.
  • הערך של endDate חייב להיות startDate או תאריך מאוחר יותר, שניהם לפני שנת 2037.
campaignBudgetId

string (int64 format)

budgetId של תקציב הקמפיין שאליו משתייך פלח התקציב של סדר ההכנסה הזה.

OptimizationObjective

הסוגים האפשריים של יעדי האופטימיזציה.

טיפוסים בני מנייה (enum)
OPTIMIZATION_OBJECTIVE_UNSPECIFIED ערך הטיפוס לא צוין או שהוא לא ידוע בגרסה הזו.
CONVERSION לתת עדיפות לחשיפות שמגדילות את נפח המכירות וההמרות.
CLICK מתן עדיפות לחשיפות שמגדילות את נפח התנועה לאתר, לאפליקציות או לחנויות האפליקציות.
BRAND_AWARENESS לתת עדיפות לחשיפות באיכות ספציפית.
CUSTOM היעד מוגדר לפי אלגוריתם הבידינג בהתאמה אישית שהוקצה.
NO_OBJECTIVE היעד לא מוגדר. אפשר להשתמש בכל מדד KPI או שיטת בידינג.

Methods

create

 יצירת הזמנת קמפיין חדשה.

delete

 מחיקה של הזמנת קמפיין.

get

 הפונקציה מקבלת הזמנת קמפיין.

list

 הצגת הזמנות להצגת מודעות בחשבון מפרסם.

listAssignedTargetingOptions

 רשימה של אפשרויות הטירגוט שהוקצו להזמנת קמפיין לפי סוגי טירגוט.

patch

 עדכון של הזמנת קמפיין קיימת.