REST Resource: advertisers.insertionOrders

משאב: InsertionOrder

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

ייצוג ב-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. כדי להפעיל הזמנת פרסום, משתמשים ב-method‏ insertionOrders.patch ומעדכנים את הסטטוס ל-ENTITY_STATUS_ACTIVE אחרי היצירה.
  • אי אפשר לשנות את הסטטוס של הזמנת קמפיין חזרה לסטטוס ENTITY_STATUS_DRAFT מכל סטטוס אחר.
  • אי אפשר להגדיר הזמנת עבודה כ-ENTITY_STATUS_ACTIVE אם הקמפיין הראשי שלה לא פעיל.
updateTime

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".
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.

אם השדה automationType של budget מוגדר לערך INSERTION_ORDER_AUTOMATION_TYPE_BUDGET או INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET, הזמנת הפרסום תחיל את שיטת הבידינג הזו על הפריטים שלה. אם שיטת הבידינג שנבחרה לא תואמת להגדרה enableOptimizedTargeting של פריט, ההגדרה של אופטימיזציית הטירגוט תתעדכן.
reservationType

enum (ReservationType)

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

enum (OptimizationObjective)

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

InsertionOrderType

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

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

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

KPI

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

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

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "kpiAmountMicros": string,
  "kpiPercentageMicros": string,
  "kpiString": string
  // End of mutually exclusive fields.
}
שדות
kpiType

enum (KpiType)

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

string (int64 format)

אופציונלי. מזהה האלגוריתם של הצעות המחיר המותאמות אישית שמשויך ל-KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. המערכת מתעלמת מהשדה הזה אם לא נבחר מדד ה-KPI המתאים.
חובה. הערך של ה-KPI. השדה הרלוונטי תואם ל-kpi_type. זו רשימה של שדות שמוציאים זה את זה. בתשובה יוגדר לכל היותר אחד מהשדות הבאים:
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)

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

רלוונטי כש-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 המערכת יכולה לשנות באופן אוטומטי את הצעות המחיר ולהעביר תקציב לפריטים הראשיים כדי לשפר את הביצועים שמוגדרים לפי bidStrategy.

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

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

patch

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