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 تلقائيًا.

إذا تم ضبط الحقل 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 Over-the-top

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

إعدادات تتحكّم في مؤشر الأداء الرئيسي (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)

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

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