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. כדי להפעיל הזמנת פרסום, משתמשים בשיטה 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 מוגדר.
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)

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

רלוונטי אם 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

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