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

enum (ReservationType)

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

enum (OptimizationObjective)

اختياريّ. هدف التحسين لطلب الإدراج.

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

OptimizationObjective

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

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

الطُرق

create

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

delete

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

get

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

list

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

listAssignedTargetingOptions

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

patch

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