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)
}
الحقول
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)

النتائج فقط. الطابع الزمني لآخر تعديل لطلب الإدراج تم تعيينه من قِبل النظام.

طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "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)

مطلوبة. مؤشر الأداء الرئيسي لطلب الإدراج

ويُشار إليه باسم "الهدف" في واجهة "مساحة العرض والفيديو 360".
budget

object (InsertionOrderBudget)

مطلوبة. إعدادات تخصيص الميزانية لطلب الإدراج
bidStrategy

object (BiddingStrategy)

استراتيجية عروض الأسعار لطلب الإدراج. بشكل تلقائي، يتم ضبط fixedBid.
reservationType

enum (ReservationType)

النتائج فقط. نوع الحجز لطلب الإدراج

InsertionOrderType

الأنواع المحتملة من طلب الإدراج

يحدّد نوع طلب الإدراج الإعدادات والخيارات السارية، مثل شكل الإعلانات أو خيارات الاستهداف.

عمليات التعداد
INSERTION_ORDER_TYPE_UNSPECIFIED نوع طلب الإدراج غير محدّد أو غير معروف.
RTB عرض الأسعار في الوقت الفعلي.
OVER_THE_TOP خدمة البث المباشر على الإنترنت:

مؤشر الأداء الرئيسي

الإعدادات التي تتحكّم في مؤشر الأداء الرئيسي لطلب الإدراج

تمثيل 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)

مطلوبة. نوع مؤشر الأداء الرئيسي.
kpiAlgorithmId

string (int64 format)

اختياريّ. رقم تعريف خوارزمية عروض الأسعار المخصّصة المرتبط بـ KPI_CUSTOM_IMPRESSION_VALUE_OVER_cost. ويتم تجاهل هذا الحقل في حال عدم اختيار مؤشر الأداء الرئيسي المناسب.
حقل الاتحاد kpi_value مطلوبة. قيمة مؤشر الأداء الرئيسي. ويتطابق الحقل ذو الصلة مع 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

سلسلة مؤشر الأداء الرئيسي، والتي يمكن أن تكون فارغة. يجب أن يكون طولها بترميز UTF-8 لا يزيد عن 100 حرف.

يسري هذا العرض عندما تكون قيمة kpiType هي KPI_TYPE_OTHER.

KpiType

أنواع مؤشرات الأداء الرئيسية (KPI) المحتملة.

عمليات التعداد
KPI_TYPE_UNSPECIFIED نوع مؤشر الأداء الرئيسي غير محدد أو غير معروف في هذا الإصدار.
KPI_TYPE_CPM مؤشر الأداء الرئيسي هو CPM (التكلفة لكل ألف ظهور).
KPI_TYPE_CPC مؤشر الأداء الرئيسي هو تكلفة النقرة (CPC).
KPI_TYPE_CPA مؤشر الأداء الرئيسي هو تكلفة الإجراء (CPA).
KPI_TYPE_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 ومؤشر الأداء الرئيسي هو التكلفة لكل ألف ظهور قابل للعرض.
KPI_TYPE_VTR مؤشر الأداء الرئيسي هو النسبة المئوية لنسبة المشاهدة على YouTube (عدد المشاهدات على YouTube لكل ظهور).
KPI_TYPE_AUDIO_COMPLETION_RATE مؤشر الأداء الرئيسي هو النسبة المئوية لمعدّل اكتمال الصوت (عدد مرات الاستماع إلى المحتوى الصوتي الكامل لكل مرة ظهور).
KPI_TYPE_VIDEO_COMPLETION_RATE مؤشر الأداء الرئيسي هو النسبة المئوية لمعدّل مشاهدة الفيديو بالكامل (عدد مشاهدات الفيديو الكاملة لكل مرة ظهور).
KPI_TYPE_CPCL يتم ضبط مؤشر الأداء الرئيسي (CPCL) بنظام تكلفة النقرة (CPCL) (تكلفة الاستماع الكامل).
KPI_TYPE_CPCV يتم ضبط مؤشر الأداء الرئيسي كتكلفة المشاهدة (CPCV) (تكلفة المشاهدة الكاملة للفيديو).
KPI_TYPE_TOS10 يتم تحديد مؤشر الأداء الرئيسي كمعدّل الوقت على الشاشة بعد أكثر من 10 ثوانٍ (النسبة المئوية لمرات الظهور القابلة للقياس غير القابلة للتخطي التي ظلت على الشاشة لمدة 10 ثوانٍ على الأقل).
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 السماح للنظام بتعديل عروض الأسعار تلقائيًا وتغيير الميزانية إلى العناصر المالكة لتحسين الأداء المحدّد في 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 لميزانية الحملة التي تشكّل شريحة الميزانية الخاصة بطلب الإدراج جزءًا منها.

الطُرق

create

 إنشاء طلب إدراج جديد

delete

 لحذف طلب إدراج

get

 تلقّي طلب إدراج

list

 يسرد طلبات الإدراج في المعلِن.

listAssignedTargetingOptions

 يسرد خيارات الاستهداف المعيّنة لطلب إدراج على مستوى أنواع الاستهداف المختلفة.

patch

 لتعديل طلب إدراج حالي