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)

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

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
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)

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

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

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 הוא אחוז שיעור הקליקים.
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 או שיטת בידינג.

שיטות

create

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

delete

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

get

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

list

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

listAssignedTargetingOptions

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

patch

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