REST Resource: advertisers.campaigns

المورد: الحملة

حملة واحدة

تمثيل JSON 
{
  "name": string,
  "advertiserId": string,
  "campaignId": string,
  "displayName": string,
  "entityStatus": enum (EntityStatus),
  "updateTime": string,
  "campaignGoal": {
    object (CampaignGoal)
  },
  "campaignFlight": {
    object (CampaignFlight)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "campaignBudgets": [
    {
      object (CampaignBudget)
    }
  ]
}
الحقول
name

string

النتائج فقط. اسم المورد الخاص بالحملة.
advertiserId

string (int64 format)

النتائج فقط. المعرّف الفريد للمعلِن الذي تنتمي إليه الحملة.
campaignId

string (int64 format)

النتائج فقط. المعرّف الفريد للحملة. يتمّ تخصيصه من قِبل النظام.
displayName

string

الحقل مطلوب. الاسم المعروض للحملة.

يجب أن يكون الترميز UTF-8 وبحجم 240 بايت كحد أقصى.
entityStatus

enum (EntityStatus)

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

  • القيم المقبولة هي ENTITY_STATUS_ACTIVE وENTITY_STATUS_ARCHIVED وENTITY_STATUS_PAUSED.
  • بالنسبة إلى طريقة campaigns.create، لا يُسمح باستخدام ENTITY_STATUS_ARCHIVED.
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"
campaignGoal

object (CampaignGoal)

الحقل مطلوب. هدف الحملة
campaignFlight

object (CampaignFlight)

الحقل مطلوب. الإنفاق المخطّط له ومدة الحملة
frequencyCap

object (FrequencyCap)

الحقل مطلوب. إعداد تحديد عدد مرّات الظهور في الحملة
campaignBudgets[]

object (CampaignBudget)

قائمة بالميزانيات المتاحة لهذه الحملة.

في حال عدم ضبط هذا الحقل، تستخدم الحملة ميزانية غير محدودة.

CampaignGoal

الإعدادات التي تتحكّم في هدف الحملة

تمثيل JSON 
{
  "campaignGoalType": enum (CampaignGoalType),
  "performanceGoal": {
    object (PerformanceGoal)
  }
}
الحقول
campaignGoalType

enum (CampaignGoalType)

الحقل مطلوب. نوع هدف الحملة.
performanceGoal

object (PerformanceGoal)

الحقل مطلوب. هدف الأداء للحملة

القيم المقبولة لـ performanceGoalType هي:

  • PERFORMANCE_GOAL_TYPE_CPM
  • PERFORMANCE_GOAL_TYPE_CPC
  • PERFORMANCE_GOAL_TYPE_CPA
  • PERFORMANCE_GOAL_TYPE_CPIAVC
  • PERFORMANCE_GOAL_TYPE_CTR
  • PERFORMANCE_GOAL_TYPE_VIEWABILITY
  • PERFORMANCE_GOAL_TYPE_OTHER

CampaignGoalType

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

عمليات التعداد
CAMPAIGN_GOAL_TYPE_UNSPECIFIED لم يتم تحديد قيمة الهدف أو أنّها غير معروفة في هذا الإصدار.
CAMPAIGN_GOAL_TYPE_APP_INSTALL زيادة عمليات تثبيت التطبيق أو التفاعلات مع التطبيق
CAMPAIGN_GOAL_TYPE_BRAND_AWARENESS زيادة الوعي بعلامة تجارية أو منتج
CAMPAIGN_GOAL_TYPE_OFFLINE_ACTION زيادة المبيعات التي تتم بلا إنترنت أو في المتجر
CAMPAIGN_GOAL_TYPE_ONLINE_ACTION زيادة الزيارات أو الإجراءات على الإنترنت

PerformanceGoal

إعدادات تتحكّم في هدف الأداء لإحدى الحملات

تمثيل JSON 
{
  "performanceGoalType": enum (PerformanceGoalType),

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "performanceGoalAmountMicros": string,
  "performanceGoalPercentageMicros": string,
  "performanceGoalString": string
  // End of mutually exclusive fields.
}
الحقول
performanceGoalType

enum (PerformanceGoalType)

الحقل مطلوب. نوع هدف الأداء
الحقل مطلوب. قيمة هدف الأداء المرتبط بـ performance_goal_type معيّن في ما يلي قائمة بالحقول التي يستبعد كلّ منها الآخر. سيتم ضبط حقل واحد على الأكثر في الرد:
performanceGoalAmountMicros

string (int64 format)

مبلغ الهدف، بالوحدات الصغيرة من عملة المعلِن

ينطبق ذلك عندما تكون قيمة performanceGoalType إحدى القيم التالية:

  • PERFORMANCE_GOAL_TYPE_CPM
  • PERFORMANCE_GOAL_TYPE_CPC
  • PERFORMANCE_GOAL_TYPE_CPA
  • PERFORMANCE_GOAL_TYPE_CPIAVC
  • PERFORMANCE_GOAL_TYPE_VCPM

على سبيل المثال، يمثّل الرقم 1500000 مقدار 1.5 وحدة عادية من العملة.
performanceGoalPercentageMicros

string (int64 format)

التمثيل العشري للنسبة المئوية للهدف بوحدات المايكرو

ينطبق ذلك عندما تكون قيمة performanceGoalType إحدى القيم التالية:

  • PERFORMANCE_GOAL_TYPE_CTR
  • PERFORMANCE_GOAL_TYPE_VIEWABILITY
  • PERFORMANCE_GOAL_TYPE_CLICK_CVR
  • PERFORMANCE_GOAL_TYPE_IMPRESSION_CVR
  • PERFORMANCE_GOAL_TYPE_VTR
  • PERFORMANCE_GOAL_TYPE_AUDIO_COMPLETION_RATE
  • PERFORMANCE_GOAL_TYPE_VIDEO_COMPLETION_RATE

على سبيل المثال، يمثّل الرقم 70000 نسبة %7 (القيمة العشرية 0.07).
performanceGoalString

string

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

ينطبق هذا الخيار عندما تكون قيمة performanceGoalType هي PERFORMANCE_GOAL_TYPE_OTHER.
نهاية الحقول التي يستبعد كلّ منها الآخر

PerformanceGoalType

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

عمليات التعداد
PERFORMANCE_GOAL_TYPE_UNSPECIFIED لم يتم تحديد نوع هدف الأداء أو أنّه غير معروف في هذا الإصدار.
PERFORMANCE_GOAL_TYPE_CPM يتم ضبط هدف الأداء في التكلفة لكل ألف ظهور.
PERFORMANCE_GOAL_TYPE_CPC يتم تحديد هدف الأداء بتكلفة النقرة.
PERFORMANCE_GOAL_TYPE_CPA يتم تحديد هدف الأداء في "التكلفة لكل إجراء".
PERFORMANCE_GOAL_TYPE_CTR يتم تحديد هدف الأداء كنسبة مئوية من نسبة النقر إلى الظهور.
PERFORMANCE_GOAL_TYPE_VIEWABILITY يتمّ ضبط هدف الأداء في نسبة إمكانية العرض.
PERFORMANCE_GOAL_TYPE_CPIAVC يتم ضبط هدف الأداء على "التكلفة لكل مرة ظهور مسموع ومرئي عند الاكتمال".
PERFORMANCE_GOAL_TYPE_CPE يتم تحديد هدف الأداء في "تكلفة المشاركة".
PERFORMANCE_GOAL_TYPE_CPV يتم ضبط هدف الأداء في "تكلفة المشاهدة".
PERFORMANCE_GOAL_TYPE_CLICK_CVR يتم ضبط هدف الأداء كنسبة مئوية لمعدّل الإحالات الناجحة الناتجة عن النقر (الإحالات الناجحة لكل نقرة).
PERFORMANCE_GOAL_TYPE_IMPRESSION_CVR يتم ضبط هدف الأداء كنسبة مئوية لمعدّل الإحالات الناجحة لكل مرّة ظهور (الإحالات الناجحة لكل مرّة ظهور).
PERFORMANCE_GOAL_TYPE_VCPM يتم ضبط هدف الأداء في "التكلفة لكل ألف ظهور قابل للعرض".
PERFORMANCE_GOAL_TYPE_VTR يتم تحديد هدف الأداء كنسبة مئوية في معدّل المشاهدة على YouTube (عدد المشاهدات على YouTube لكلّ مرّة ظهور).
PERFORMANCE_GOAL_TYPE_AUDIO_COMPLETION_RATE يتم ضبط هدف الأداء كنسبة مئوية لمعدّل إكمال الملف الصوتي (عدد مرات الاستماع إلى الملف الصوتي بالكامل لكل مرة ظهور).
PERFORMANCE_GOAL_TYPE_VIDEO_COMPLETION_RATE يتم تحديد هدف الأداء كنسبة مئوية لمعدّل مشاهدة الفيديو بالكامل (عدد مرات مشاهدة الفيديو بالكامل لكل مرة ظهور).
PERFORMANCE_GOAL_TYPE_OTHER تم ضبط هدف الأداء على "غير ذلك".

CampaignFlight

الإعدادات التي تتتبّع الإنفاق المُخطّط له ومدة الحملة

تمثيل JSON 
{
  "plannedSpendAmountMicros": string,
  "plannedDates": {
    object (DateRange)
  }
}
الحقول
plannedSpendAmountMicros

string (int64 format)

المبلغ الذي من المتوقّع أن تنفقه الحملة مقابل plannedDates المحدّد لها. لن يحدّ هذا الإعداد من عرض الإعلانات، ولكن سيتم استخدامه لتتبُّع الإنفاق في واجهة مستخدم "مساحة العرض والفيديو 360".

المبلغ بوحدة Micro يجب أن تكون القيمة أكبر من 0 أو مساوية له. على سبيل المثال، يمثّل الرقم 500000000 مبلغ 500 وحدة عادية من العملة.
plannedDates

object (DateRange)

الحقل مطلوب. التواريخ المتوقّع أن يتم فيها عرض الحملة ويتم حلّها بالنسبة إلى المنطقة الزمنية للمعلن الرئيسي.

  • لن تؤثّر التواريخ المحدّدة هنا في عرض الإعلانات. ويتم استخدامها لإنشاء التنبيهات والتحذيرات. على سبيل المثال، إذا كان تاريخ عرض أي طلب إدراج خاص بطفل خارج نطاق هذه التواريخ، ستعرض واجهة المستخدِم تحذيرًا.
  • يجب إدخال startDate ويجب أن يكون تاريخ اليوم أو تاريخًا لاحقًا.
  • endDate هو حقل اختياري. في حال تحديدها، يجب أن تكون startDate أو تاريخًا لاحقًا.
  • يجب أن يكون أي تاريخ محدّد قبل عام 2037.

CampaignBudget

الإعدادات التي تتحكّم في طريقة تخصيص ميزانية الحملة

تمثيل JSON 
{
  "budgetId": string,
  "displayName": string,
  "budgetUnit": enum (BudgetUnit),
  "budgetAmountMicros": string,
  "dateRange": {
    object (DateRange)
  },
  "externalBudgetSource": enum (ExternalBudgetSource),
  "externalBudgetId": string,
  "invoiceGroupingId": string,
  "prismaConfig": {
    object (PrismaConfig)
  }
}
الحقول
budgetId

string (int64 format)

المعرّف الفريد لميزانية الحملة. يتمّ تخصيصه من قِبل النظام. لا تضبط هذا الخيار للميزانيات الجديدة.

يجب تضمينها عند تعديل الميزانيات أو إضافتها إلى campaignBudgets. بخلاف ذلك، سيتم إنشاء معرّف جديد وتعيينه.
displayName

string

الحقل مطلوب. الاسم المعروض للميزانية

يجب أن يكون الترميز UTF-8 وبحجم 240 بايت كحد أقصى.
budgetUnit

enum (BudgetUnit)

الحقل مطلوب. غير قابل للتغيير تحدّد ما إذا كانت الميزانية تُقاس بالعملة أو مرّات الظهور.
budgetAmountMicros

string (int64 format)

الحقل مطلوب. إجمالي المبلغ الذي يمكن أن تحدّده شرائح طلب الإدراج المرتبطة كميزانية.

المبلغ بوحدة Micro يجب أن تكون القيمة أكبر من 0. على سبيل المثال، يمثّل الرقم 500000000 مبلغ 500 وحدة عادية من العملة.
dateRange

object (DateRange)

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

يجب أن يكون كل من startDate وendDate قبل عام 2037.
externalBudgetSource

enum (ExternalBudgetSource)

الحقل مطلوب. تمثّل هذه السمة المصدر الخارجي للميزانية.
externalBudgetId

string

غير قابل للتغيير تمثّل هذه السمة رقم التعريف الذي يحدّد هذه الميزانية للمصدر الخارجي.

في حال ضبط هذا الحقل على "طلب الشراء على مستوى الميزانية"، سيتم تضمين هذا المعرّف في الفاتورة لكل مرّات الظهور التي يتم عرضها مقابل هذه الميزانية.

يجب أن يكون فريدًا ضمن الحملة.
invoiceGroupingId

string

غير قابل للتغيير المعرّف المستخدَم لتجميع الميزانيات التي سيتم تضمينها في الفاتورة نفسها

في حال ضبط هذا الحقل على "معرّف تجميع فواتير الميزانية"، سيتم تجميع كل externalBudgetId التي تشترك في invoiceGroupingId نفسها في الفاتورة نفسها.
prismaConfig

object (PrismaConfig)

بيانات وصفية إضافية لاستخدامها في أداة Mediaocean Prisma

مطلوب لميزانيات Mediaocean.

ينطبق هذا العرض على المعلِنين في prismaEnabled فقط.

ExternalBudgetSource

مصدر خارجي لشريحة ميزانية الحملة

عمليات التعداد
EXTERNAL_BUDGET_SOURCE_UNSPECIFIED لم يتم تحديد قيمة مصدر الميزانية الخارجية أو أنّها غير معروفة في هذا الإصدار.
EXTERNAL_BUDGET_SOURCE_NONE لا تتضمّن الميزانية مصدرًا خارجيًا.
EXTERNAL_BUDGET_SOURCE_MEDIA_OCEAN مصدر الميزانية هو Mediaocean.

PrismaConfig

إعدادات خاصة بأداة Mediaocean Prisma.

تمثيل JSON 
{
  "prismaType": enum (PrismaType),
  "prismaCpeCode": {
    object (PrismaCpeCode)
  },
  "supplier": string
}
الحقول
prismaType

enum (PrismaType)

الحقل مطلوب. نوع Prisma
prismaCpeCode

object (PrismaCpeCode)

الحقل مطلوب. رموز العميل والمنتج والتقدير ذات الصلة من أداة Mediaocean Prisma
supplier

string

الحقل مطلوب. الجهة التي خصّصت هذه الميزانية (منصّة عرض الطلب أو الموقع الإلكتروني أو غير ذلك)

PrismaType

الأنواع المحتملة لميزانية Prisma

عمليات التعداد
PRISMA_TYPE_UNSPECIFIED لم يتم تحديد النوع أو أنّه غير معروف في هذا الإصدار.
PRISMA_TYPE_DISPLAY نوع الشاشة
PRISMA_TYPE_VIDEO نوع الفيديو
PRISMA_TYPE_AUDIO نوع الصوت
PRISMA_TYPE_SOCIAL تمثّل هذه السمة نوع الشبكة الاجتماعية.
PRISMA_TYPE_FEE تمثّل هذه السمة نوع الرسوم.

PrismaCpeCode

يتيح لك "مركز دفعات Google" البحث عن الحقول المكوّنة لهذا الرمز وفلترتها.

تمثيل JSON 
{
  "prismaClientCode": string,
  "prismaProductCode": string,
  "prismaEstimateCode": string
}
الحقول
prismaClientCode

string

تمثّل هذه السمة رمز عميل Prisma.
prismaProductCode

string

تمثّل هذه السمة رمز منتج Prisma.
prismaEstimateCode

string

تمثّل هذه السمة رمز تقدير Prisma.

الطُرق

create

 تُنشئ هذه الطريقة حملة جديدة.

delete

 لحذف حملة نهائيًا

get

 تعرض هذه الطريقة إحدى الحملات.

list

 تعرض هذه الطريقة الحملات في حساب أحد المعلِنين.

patch

 تعديل حملة حالية