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)

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

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

object (InsertionOrderBudget)

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

object (BiddingStrategy)

اختيارية: استراتيجية عروض الأسعار لطلب الإدراج يتم ضبط fixedBid تلقائيًا.

إذا تم ضبط الحقل automationType في budget على 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 الإعلانات الخارجية:

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

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

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

على سبيل المثال: يمثّل الرقم 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 مؤشر الأداء الرئيسي هو التكلفة لكل ألف ظهور.
KPI_TYPE_CPC مؤشر الأداء الرئيسي هو تكلفة النقرة.
KPI_TYPE_CPA مؤشر الأداء الرئيسي هو التكلفة لكل إجراء (CPA).
KPI_TYPE_CTR مؤشر الأداء الرئيسي هو النسبة المئوية لنسبة النقر إلى الظهور (CTR).
KPI_TYPE_VIEWABILITY مؤشر الأداء الرئيسي هو النسبة المئوية لإمكانية العرض.
KPI_TYPE_CPIAVC مؤشر الأداء الرئيسي هو CPIAVC (التكلفة لكل ظهور مسموع ومرئي عند الاكتمال).
KPI_TYPE_CPE مؤشر الأداء الرئيسي هو تكلفة المشاركة (CPE).
KPI_TYPE_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 يتم ضبط مؤشر الأداء الرئيسي على معدّل مدة الظهور على الشاشة لمدة 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 يمكنك السماح للنظام بتعديل عروض الأسعار تلقائيًا ونقل الميزانية إلى العناصر الإعلانية التي تملكها لتحسين الأداء المحدّد من خلال bidStrategy.

InsertionOrderBudgetSegment

الإعدادات التي تتحكّم في ميزانية شريحة ميزانية واحدة

تمثيل JSON 
{
  "budgetAmountMicros": string,
  "description": string,
  "dateRange": {
    object (DateRange)
  },
  "campaignBudgetId": string
}
الحقول
budgetAmountMicros

string (int64 format)

الحقل مطلوب. مبلغ الميزانية الذي سينفقه طلب الإدراج في dateRange المحدّد. يتم عرض المبلغ بوحدة Micro. يجب أن تكون القيمة أكبر من 0. على سبيل المثال، يمثّل الرقم 500000000‏ 500 وحدة عادية من العملة.
description

string

اختيارية: وصف شريحة الميزانية ويمكن استخدامها لإدخال معلومات طلب الشراء لكل شريحة ميزانية وطباعة هذه المعلومات على الفواتير.

يجب أن يكون بترميز UTF-8.
dateRange

object (DateRange)

الحقل مطلوب. إعدادات تاريخَي البدء والانتهاء لشريحة الميزانية ويتم حلّها وفقًا للمنطقة الزمنية للمعلِن الرئيسي.

  • عند إنشاء شريحة ميزانية جديدة، يجب أن يكون كلّ من startDate وendDate في المستقبل.
  • تتضمّن شريحة الميزانية الحالية التي لها startDate في الماضي endDate قابلاً للتغيير ولكنّ startDate غير قابل للتغيير.
  • يجب أن يكون تاريخ "endDate" هو ‎startDate أو تاريخ لاحق، على أن يكون كلاهما قبل عام 2037.
campaignBudgetId

string (int64 format)

اختيارية: تمثّل هذه السمة budgetId ميزانية الحملة التي تشكّل شريحة ميزانية طلب الإدراج هذه جزءًا منها.

OptimizationObjective

الأنواع المحتملة لأهداف التحسين

عمليات التعداد
OPTIMIZATION_OBJECTIVE_UNSPECIFIED لم يتم تحديد قيمة النوع أو أنّها غير معروفة في هذا الإصدار.
CONVERSION إعطاء الأولوية لمرات الظهور التي تزيد من المبيعات والإحالات الناجحة
CLICK إعطاء الأولوية لمرات الظهور التي تزيد من عدد الزيارات إلى الموقع الإلكتروني والتطبيقات ومتاجر التطبيقات
BRAND_AWARENESS إعطاء الأولوية لمرات الظهور ذات الجودة المحدّدة
CUSTOM يتم تحديد الهدف من خلال خوارزمية عروض الأسعار المخصّصة التي تم تعيينها.
NO_OBJECTIVE لم يتم تحديد الهدف. يمكن استخدام أي مؤشر أداء رئيسي أو استراتيجية عروض أسعار.

الطُرق

create

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

delete

 تحذف هذه الطريقة طلب إدراج.

get

 للحصول على طلب إدراج

list

 تعرض هذه الطريقة طلبات الترتيب لدى معلِن معيّن.

patch

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