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 מוגדר.

אם השדה budget automationType מוגדר לערך 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 ישירות ללקוח.

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. הסכום מצוין ב-Micros. הערך חייב להיות גדול מ-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

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