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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 )

الزامی. هدف بهینه‌سازی ترتیب درج.

نوع سفارش درج

انواع احتمالی دستور درج.

نوع سفارش درج، تنظیمات و گزینه‌های قابل اجرا، مانند قالب تبلیغات یا گزینه‌های هدف‌گیری را تعیین می‌کند.

انوم‌ها
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

برای مثال: ۱۵۰۰۰۰۰ نشان دهنده ۱.۵ واحد استاندارد از ارز است.

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 باشد، قابل اجرا است.

کی‌پی‌آی‌تایپ

انواع شاخص‌های کلیدی عملکرد (KPI) احتمالی.

انوم‌ها
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) نرخ بازدید یوتیوب (تعداد بازدیدهای یوتیوب به ازای هر نمایش) است.
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) بر اساس نرخ زمان حضور روی صفحه نمایش بیش از ۱۰ ثانیه (درصد نمایش‌های قابل اندازه‌گیری و غیرقابل رد شدن که حداقل ۱۰ ثانیه روی صفحه بوده‌اند) تنظیم می‌شود.
KPI_TYPE_MAXIMIZE_PACING این شاخص کلیدی عملکرد (KPI) به گونه‌ای تنظیم شده است که ضمن اولویت‌بندی هزینه کردن کل بودجه، تأثیر برند را به حداکثر برساند.
KPI_TYPE_CUSTOM_IMPRESSION_VALUE_OVER_COST شاخص کلیدی عملکرد (KPI) بر اساس ارزش نمایش سفارشی تقسیم بر هزینه تعیین می‌شود.
KPI_TYPE_OTHER KPI یک مقدار دیگر است.

بودجه‌ی درج سفارش

تنظیماتی که نحوه تخصیص بودجه سفارش درج را کنترل می‌کنند.

نمایش JSON 
{
  "budgetUnit": enum (BudgetUnit),
  "automationType": enum (InsertionOrderAutomationType),
  "budgetSegments": [
    {
      object (InsertionOrderBudgetSegment)
    }
  ]
}
فیلدها
budgetUnit

enum ( BudgetUnit )

الزامی. تغییرناپذیر. واحد بودجه مشخص می‌کند که آیا بودجه بر اساس واحد پول است یا بر اساس تعداد نمایش.

automationType

enum ( InsertionOrderAutomationType )

اختیاری. نوع اتوماسیون مورد استفاده برای مدیریت پیشنهاد قیمت و بودجه برای سفارش درج.

اگر این فیلد در هنگام ایجاد مشخص نشده باشد، مقدار پیش‌فرض INSERTION_ORDER_AUTOMATION_TYPE_NONE خواهد بود.

budgetSegments[]

object ( InsertionOrderBudgetSegment )

الزامی. فهرست بخش‌های بودجه. از یک بخش بودجه برای مشخص کردن بودجه‌ای خاص برای یک دوره زمانی مشخص که سفارش درج در حال اجرا است، استفاده کنید.

نوع اتوماسیون درج سفارش

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

انوم‌ها
INSERTION_ORDER_AUTOMATION_TYPE_UNSPECIFIED گزینه اتوماسیون سفارش درج در این نسخه مشخص نشده یا ناشناخته است.
INSERTION_ORDER_AUTOMATION_TYPE_BUDGET تخصیص خودکار بودجه. به سیستم اجازه دهید تا به طور خودکار بودجه را به ردیف‌های مربوط به خود منتقل کند تا عملکرد تعریف شده توسط kpi را بهینه کند. هیچ اتوماسیونی در تنظیمات پیشنهاد قیمت وجود ندارد.
INSERTION_ORDER_AUTOMATION_TYPE_NONE عدم خودکارسازی پیشنهاد قیمت یا بودجه در سطح سفارش درج. پیشنهاد قیمت و بودجه باید به صورت دستی در سطح ردیف کالا پیکربندی شوند.
INSERTION_ORDER_AUTOMATION_TYPE_BID_BUDGET به سیستم اجازه دهید تا به طور خودکار پیشنهادات را تنظیم کرده و بودجه را به سمت اقلام ردیف مالکیت تغییر دهد تا عملکرد تعریف شده توسط kpi را بهینه کند.

بخش درجسفارشبودجه

تنظیماتی که بودجه یک بخش بودجه واحد را کنترل می‌کنند.

نمایش 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 یا بعد از آن باشد، هر دو قبل از سال ۲۰۳۷.
campaignBudgetId

string ( int64 format)

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

هدف بهینه‌سازی

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

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

روش‌ها

create

 یک ترتیب درج جدید ایجاد می‌کند.

delete

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

get

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

list

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

listAssignedTargetingOptions

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

patch

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