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 کدبندی شده باشد و حداکثر اندازه آن ۲۴۰ بایت باشد.
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-نرمال‌شده است و از ۰، ۳، ۶، یا ۹ رقم اعشاری استفاده می‌کند. انحراف‌های غیراز «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

انواع ممکن «سفارش درج».

نوع «دستور درج» تعیین می‌کند کدام تنظیمات و گزینه‌ها قابل‌اعمال هستند، مثلاً قالب آگهی‌ها یا گزینه‌های هدف‌یابی.

شمارشی‌ها
INSERTION_ORDER_TYPE_UNSPECIFIED نوع سفارش درج مشخص نشده است یا ناشناخته است.
RTB پیشنهاد قیمت هم‌زمان.
OVER_THE_TOP اغراق‌آمیز.
OUT_OF_HOME خارج از خانه.

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)

الزامی. نوع «شاخص کلیدی عملکرد».
kpiAlgorithmId

string (int64 format)

اختیاری. شناسه الگوریتم پیشنهاد قیمت سفارشی مرتبط با KPI_CUSTOM_IMPRESSION_VALUE_OVER_COST. اگر شاخص کلیدی عملکرد مناسب انتخاب نشده باشد، این فیلد نادیده گرفته می‌شود.
الزامی. مقدار «شاخص کلیدی عملکرد». فیلد مربوطه با kpi_type مطابقت دارد. در زیر فهرستی از فیلدهای متقابلاً انحصاری آمده است. حداکثر یکی از فیلدها در پاسخ تنظیم خواهد شد:
kpiAmountMicros

string (int64 format)

مبلغ هدف، به میکرو واحد پول تبلیغ‌کننده.

قابل‌اعمال وقتی kpiType یکی از موارد زیر باشد:

  • KPI_TYPE_CPM
  • KPI_TYPE_CPC
  • KPI_TYPE_CPA
  • KPI_TYPE_CPIAVC
  • KPI_TYPE_VCPM

برای مثال: ۱۵۰۰۰۰۰ نشان‌دهنده ۱٫۵ واحد استاندارد از ارز است.
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

برای مثال: ۷۰۰۰۰ نشان‌دهنده ۷٪ (اعشاری ۰٫۰۷) است.
kpiString

string

رشته KPI که می‌تواند خالی باشد. باید با کدبندی UTF-8 و طول حداکثر ۱۰۰ نویسه باشد.

قابل‌اعمال وقتی kpiType KPI_TYPE_OTHER است.
پایان فیلدهای متقابلاً انحصاری.

KpiType

انواع ممکن نشانگر عملکرد کلید (KPI).

شمارشی‌ها
KPI_TYPE_UNSPECIFIED نوع شاخص کلیدی عملکرد مشخص نشده است یا در این نسخه ناشناخته است.
KPI_TYPE_CPM شاخص کلیدی عملکرد CPM (هزارظهوربها) است.
KPI_TYPE_CPC شاخص کلیدی عملکرد CPC (کلیک‌بها) است.
KPI_TYPE_CPA شاخص کلیدی عملکرد، کنش‌بها (CPA) است.
KPI_TYPE_CTR شاخص کلیدی عملکرد، درصد نرخ کلیک‌گذری (CTR) است.
KPI_TYPE_VIEWABILITY «شاخص کلیدی عملکرد» عبارت است از درصد «قابل‌مشاهده بودن».
KPI_TYPE_CPIAVC شاخص کلیدی عملکرد CPIAVC (هزارظهوربهای شنیداری و دیداری در پایان) است.
KPI_TYPE_CPE شاخص کلیدی عملکرد، تعامل‌بها (CPE) است.
KPI_TYPE_CPV شاخص کلیدی عملکرد در CPV (بازدیدبها) تنظیم شده است.
KPI_TYPE_CLICK_CVR شاخص کلیدی عملکرد، درصد نرخ تبدیل کلیک (تبدیل به‌ازای هر کلیک) است.
KPI_TYPE_IMPRESSION_CVR شاخص کلیدی عملکرد عبارت است از درصد نرخ تبدیل ظهور (تبدیل‌ها به‌ازای هر ظهور).
KPI_TYPE_VCPM شاخص کلیدی عملکرد، هزارظهوربهای مشاهده‌شدنی (VCPM) است.
KPI_TYPE_VTR شاخص کلیدی عملکرد، درصد نرخ بازدید YouTube (بازدیدهای YouTube به‌ازای هر ظهور) است.
KPI_TYPE_AUDIO_COMPLETION_RATE شاخص کلیدی عملکرد عبارت است از درصد نرخ تکمیل صدا (گوش دادن کامل به صدا به‌ازای هر ظهور).
KPI_TYPE_VIDEO_COMPLETION_RATE شاخص کلیدی عملکرد عبارت است از درصد نرخ تکمیل ویدیو (بازدیدهای کامل ویدیو به‌ازای هر ظهور).
KPI_TYPE_CPCL شاخص کلیدی عملکرد در CPCL (هزینه به‌ازای گوش دادن کامل به صدا) تنظیم شده است.
KPI_TYPE_CPCV شاخص کلیدی عملکرد در CPCV (قیمت بازدیدبها) تنظیم شده است.
KPI_TYPE_TOS10 شاخص کلیدی عملکرد براساس نرخ زمان حضور روی صفحه به‌مدت ۱۰ ثانیه یا بیشتر تنظیم شده است (درصد ظهورهای قابل‌اندازه‌گیری و ردنشدنی که حداقل ۱۰ ثانیه روی صفحه بوده‌اند).
KPI_TYPE_MAXIMIZE_PACING شاخص کلیدی عملکرد برای بیشینه‌سازی تأثیر نمانام تنظیم شده است و درعین‌حال هزینه کردن کل بودجه را در اولویت قرار می‌دهد.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST شاخص کلیدی عملکرد در مقدار سفارشی آگهی نشان داده شده تقسیم بر هزینه تنظیم شده است.
KPI_TYPE_OTHER شاخص کلیدی عملکرد مقدار دیگری است.

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

گزینه‌های ممکن برای خودکارسازی قیمت پیشنهادی و بودجه سفارش درج.

شمارشی‌ها
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 داده‌شده هزینه خواهد کرد. مقدار به میکرو است. باید بزرگ‌تر از ۰ باشد. برای مثال، ۵۰۰۰۰۰۰۰۰ نشان‌دهنده ۵۰۰ واحد استاندارد از ارز است.
description

string

اختیاری. شرح بخش بودجه. می‌توان از آن برای وارد کردن اطلاعات «سفارش خرید» برای هر بخش بودجه استفاده کرد و این اطلاعات را در صورت‌حساب‌ها چاپ کرد.

باید کدبندی UTF-8 داشته باشد.
dateRange

object (DateRange)

الزامی. تنظیمات تاریخ شروع و پایان بخش بودجه. این تاریخ‌ها نسبت به منطقه زمانی آگهی‌دهنده اصلی حل‌وفصل می‌شوند.

  • هنگام ایجاد بخش بودجه جدید، هم startDate و هم endDate باید در آینده باشد.
  • بخش بودجه موجود با startDate در گذشته دارای endDate تغییرپذیر اما startDate تغییرناپذیر است.
  • endDate باید startDate یا جدیدتر باشد، هر دو قبل‌از سال ۲۰۳۷.
campaignBudgetId

string (int64 format)

اختیاری. budgetId بودجه پویشی که این بخش بودجه سفارش درج بخشی از آن است.

OptimizationObjective

انواع ممکن اهداف بهینه‌سازی.

شمارشی‌ها
OPTIMIZATION_OBJECTIVE_UNSPECIFIED مقدار نوع مشخص نشده است یا در این نسخه ناشناخته است.
CONVERSION ظهورهایی را که فروش و تبدیل‌ها را افزایش می‌دهند اولویت‌بندی کنید.
CLICK ظهورهایی را که ترافیک وب‌سایت، برنامه‌ها، و فروشگاه‌های برنامه را افزایش می‌دهند در اولویت قرار دهید.
BRAND_AWARENESS ظهورهای با کیفیت خاص را در اولویت قرار دهید.
CUSTOM هدف براساس الگوریتم پیشنهاد قیمت دادن سفارشی اختصاص‌داده‌شده تعریف می‌شود.
NO_OBJECTIVE هدف تعریف نشده است. هر شاخص کلیدی عملکرد یا استراتژی پیشنهاد قیمتی را می‌توان استفاده کرد.

روش‌ها

create

 دستور درج جدیدی ایجاد می‌کند.

delete

 سفارش درج را حذف می‌کند.

get

 سفارش درجی را دریافت می‌کند.

list

 سفارش‌های درج را در تبلیغ‌کننده فهرست می‌کند.

patch

 دستور درج موجود را به‌روز می‌کند.