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 يتم ضبط هدف الأداء في التكلفة لكل إجراء (CPA).
PERFORMANCE_GOAL_TYPE_CTR يتم ضبط هدف الأداء على نسبة النقر إلى الظهور.
PERFORMANCE_GOAL_TYPE_VIEWABILITY يتم ضبط هدف الأداء على نسبة مئوية لإمكانية العرض.
PERFORMANCE_GOAL_TYPE_CPIAVC يتم ضبط هدف الأداء على أنّه التكلفة لكل ظهور مسموع ومرئي عند الاكتمال.
PERFORMANCE_GOAL_TYPE_CPE يتم ضبط هدف الأداء على تكلفة المشاركة (CPE).
PERFORMANCE_GOAL_TYPE_CPV يتم ضبط هدف الأداء على تكلفة المشاهدة.
PERFORMANCE_GOAL_TYPE_CLICK_CVR يتم ضبط هدف الأداء بالنسبة المئوية لمعدل الإحالات الناجحة الناتجة عن النقر (الإحالات الناجحة لكل نقرة).
PERFORMANCE_GOAL_TYPE_IMPRESSION_CVR يتم ضبط هدف الأداء بالنسبة المئوية لمعدّل الإحالات الناجحة لكل مرّة ظهور (الإحالات الناجحة لكل مرّة ظهور).
PERFORMANCE_GOAL_TYPE_VCPM يتم ضبط هدف الأداء على 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

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