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)
  },
  "performanceGoal": {
    object (PerformanceGoal)
  },
  "budget": {
    object (InsertionOrderBudget)
  },
  "bidStrategy": {
    object (BiddingStrategy)
  },
  "reservationType": enum (ReservationType),
  "billableOutcome": enum (BillableOutcome)
}
الحقول
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) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "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)

تفاصيل إضافية عن الدمج لطلب الإدراج

performanceGoal

object (PerformanceGoal)

مطلوب. هدف الأداء لطلب الإدراج

budget

object (InsertionOrderBudget)

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

bidStrategy

object (BiddingStrategy)

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

reservationType

enum (ReservationType)

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

billableOutcome

enum (BillableOutcome)

غير قابل للتغيير. النتيجة القابلة للفوترة لطلب الإدراج.

تم إيقاف ميزة الشراء المستند إلى النتائج نهائيًا. BILLABLE_OUTCOME_PAY_PER_IMPRESSION هي القيمة الصالحة الوحيدة.

InsertionOrderType

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

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

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

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

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 من ميزانية الحملة التي يشكّل جزء الميزانية الخاص بطلب الإدراج هذا جزءًا منها

BillableOutcome

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

عمليات التعداد
BILLABLE_OUTCOME_UNSPECIFIED نتيجة غير محدّدة قابلة للفوترة.
BILLABLE_OUTCOME_PAY_PER_IMPRESSION الدفع مقابل كل مرة ظهور.
BILLABLE_OUTCOME_PAY_PER_CLICK

الدفع بالنقرة.

BILLABLE_OUTCOME_PAY_PER_VIEWABLE_IMPRESSION

الدفع مقابل كل مشاهدة نشطة

الطُرق

create

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

delete

يؤدي هذا الإجراء إلى حذف طلب إدراج.

get

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

list

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

listAssignedTargetingOptions

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

patch

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