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)

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

חותמת זמן בפורמט 'Zulu' בפורמט RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות אחרי הנקודה. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
partnerCosts[]

object (PartnerCost)

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

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

object (Pacing)

חובה. ההגדרה של מהירות ניצול התקציב של הזמנת הקמפיין.
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

לדוגמה: המספר 1500,000 מייצג 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 הוא אחוז שיעור הקליקים.
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

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