Method: customers.generateKeywordForecastMetrics

تعرض مقاييس (مثل مرات الظهور والنقرات والتكلفة الإجمالية) لتوقّعات كلمة رئيسية للحملة المحدّدة.

قائمة الأخطاء الملموسة: AuthenticationError AuthorizationError CollectionSizeError HeaderError InternalError QuotaError RequestError

طلب HTTP

POST https://googleads.googleapis.com/v16/customers/{customerId}:generateKeywordForecastMetrics

يستخدم عنوان URL بنية تحويل الترميز gRPC.

معلمات المسار

المَعلمات
customerId

string

رقم تعريف العميل.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "forecastPeriod": {
    object (DateRange)
  },
  "campaign": {
    object (CampaignToForecast)
  },
  "currencyCode": string
}
الحقول
forecastPeriod

object (DateRange)

النطاق الزمني للتوقعات. يجب أن يكون تاريخ البدء في المستقبل وأن يكون تاريخ الانتهاء في غضون عام واحد بدءًا من اليوم. المنطقة الزمنية المرجعية المستخدَمة هي المنطقة الزمنية لأحد حسابات "إعلانات Google" التي يملكها العميل. وفي حال ترك هذه السياسة بدون ضبط، سيتم استخدام نطاق زمني تلقائي يتراوح بين الأحد المقبل ويوم السبت التالي.
campaign

object (CampaignToForecast)

مطلوبة. الحملة المستخدَمة في التوقّعات.
currencyCode

string

العملة المستخدمة لتحويل سعر الصرف. بشكل تلقائي، يتم استخدام عملة حساب العميل. لا يجب ضبط هذا الحقل إلا إذا كانت العملة مختلفة عن عملة الحساب. يمكن العثور على قائمة رموز العملات الصالحة على الرابط https://developers.google.com/google-ads/api/data/codes-formats#currency-codes.

نص الاستجابة

رسالة الرد بخصوص [KeywordPlanIdeaService.GenerateKeywordتوقّعMetrics].

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "campaignForecastMetrics": {
    object (KeywordForecastMetrics)
  }
}
الحقول
campaignForecastMetrics

object (KeywordForecastMetrics)

نتائج توقّعات الحملة

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/adwords

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.

CampaignToForecast

حملة لإنشاء توقعات لحملة الكلمات الرئيسية.

تمثيل JSON 
{
  "languageConstants": [
    string
  ],
  "geoModifiers": [
    {
      object (CriterionBidModifier)
    }
  ],
  "keywordPlanNetwork": enum (KeywordPlanNetwork),
  "negativeKeywords": [
    {
      object (KeywordInfo)
    }
  ],
  "biddingStrategy": {
    object (CampaignBiddingStrategy)
  },
  "adGroups": [
    {
      object (ForecastAdGroup)
    }
  ],
  "conversionRate": number
}
الحقول
languageConstants[]

string

قائمة أسماء موارد اللغات المطلوب استهدافها. يكون اسم المورد بالتنسيق "languageConstants/{criterionId}". راجع https://developers.google.com/google-ads/api/data/codes-formats#languages للحصول على قائمة برموز معايير اللغة.
geoModifiers[]

object (CriterionBidModifier)

المواقع الجغرافية المستهدَفة. يجب أن تكون المواقع الجغرافية فريدة.
keywordPlanNetwork

enum (KeywordPlanNetwork)

مطلوبة. الشبكة المستخدمة للاستهداف.
negativeKeywords[]

object (KeywordInfo)

قائمة الكلمات الرئيسية السلبية التي سيتم استخدامها في الحملة عند إجراء التوقعات.
biddingStrategy

object (CampaignBiddingStrategy)

مطلوبة. استراتيجية عروض الأسعار للحملة.
adGroups[]

object (ForecastAdGroup)

المجموعات الإعلانية في الحملة الجديدة المطلوب توقّعها.
conversionRate

number

معدل الإحالات الناجحة المتوقع (عدد الإحالات الناجحة مقسومًا على إجمالي عدد النقرات) كما حدّده المستخدم. يتم التعبير عن هذه القيمة كقيمة عشرية، لذا يجب إدخال معدل إحالة ناجحة متوقّع يبلغ 2% على النحو التالي 0.02. وفي حال ترك هذا الحقل فارغًا، سيتم استخدام معدل إحالات ناجحة مقدَّر.

CriterionBidModifier

معدِّل عروض أسعار معيار الموقع الجغرافي.

تمثيل JSON 
{
  "geoTargetConstant": string,
  "bidModifier": number
}
الحقول
geoTargetConstant

string

اسم المورد للموقع الجغرافي المطلوب استهدافه يكون اسم المورد بالتنسيق "geoTargetConstants/{criterionId}".
bidModifier

number

تمثّل هذه السمة المُضاعِف المرتبط بالمعيارId. وفي حال ضبطها، لا يمكن أن تكون هذه القيمة 0.

CampaignBiddingStrategy

استراتيجيات عروض الأسعار المتاحة لتوقعات الحملات الجديدة.

تمثيل JSON 
{

  // Union field bidding_strategy can be only one of the following:
  "manualCpcBiddingStrategy": {
    object (ManualCpcBiddingStrategy)
  },
  "maximizeClicksBiddingStrategy": {
    object (MaximizeClicksBiddingStrategy)
  },
  "maximizeConversionsBiddingStrategy": {
    object (MaximizeConversionsBiddingStrategy)
  }
  // End of list of possible types for union field bidding_strategy.
}
الحقول
حقل الاتحاد bidding_strategy إستراتيجيات عروض الأسعار. يمكن أن يكون الحقل "bidding_strategy" واحدًا فقط مما يلي:
manualCpcBiddingStrategy

object (ManualCpcBiddingStrategy)

استخدِم استراتيجية عروض أسعار النقرة اليدوية للتوقّعات.
maximizeClicksBiddingStrategy

object (MaximizeClicksBiddingStrategy)

استخدِم استراتيجية عروض أسعار "الحصول على الحد الأقصى من النقرات" لوضع التوقّعات.
maximizeConversionsBiddingStrategy

object (MaximizeConversionsBiddingStrategy)

استخدِم استراتيجية عروض أسعار "تحقيق الحد الأقصى من الإحالات الناجحة" من أجل وضع التوقّعات.

ManualCpcBiddingStrategy

استراتيجية عروض أسعار النقرة اليدوية.

تمثيل JSON 
{
  "maxCpcBidMicros": string,
  "dailyBudgetMicros": string
}
الحقول
maxCpcBidMicros

string (int64 format)

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

string (int64 format)

ميزانية على مستوى الحملة بالمايكرو. وفي حال ضبطها، يتم فرض حد أدنى لقيمة العملة المحلية المستخدَمة في الحملة. سيحدث خطأ أثناء عرض القيمة الصغرى في حال ضبط هذا الحقل على قيمة منخفضة جدًا.

MaximizeClicksBiddingStrategy

استراتيجية عروض أسعار الحصول على الحد الأقصى من النقرات.

تمثيل JSON 
{
  "dailyTargetSpendMicros": string,
  "maxCpcBidCeilingMicros": string
}
الحقول
dailyTargetSpendMicros

string (int64 format)

مطلوبة. الإنفاق الهدف اليومي بالمايكرو والمستخدم للتقدير. يتم فرض حد أدنى لقيمة العملة المحلية المستخدَمة في الحملة. سيحدث خطأ أثناء عرض القيمة الصغرى في حال ضبط هذا الحقل على قيمة منخفضة جدًا.
maxCpcBidCeilingMicros

string (int64 format)

الحد الأقصى لعروض الأسعار القصوى للنقرة بالمايكرو.

MaximizeConversionsBiddingStrategy

استراتيجية عروض أسعار "تحقيق الحد الأقصى من الإحالات الناجحة".

تمثيل JSON 
{
  "dailyTargetSpendMicros": string
}
الحقول
dailyTargetSpendMicros

string (int64 format)

مطلوبة. الإنفاق الهدف اليومي بالمايكرو والمستخدم للتقدير. يجب أن تكون هذه القيمة أكبر من صفر.

ForecastAdGroup

المجموعة الإعلانية التي تشكّل جزءًا من حملة يمكن وضع توقّعات لها.

تمثيل JSON 
{
  "biddableKeywords": [
    {
      object (BiddableKeyword)
    }
  ],
  "negativeKeywords": [
    {
      object (KeywordInfo)
    }
  ],
  "maxCpcBidMicros": string
}
الحقول
biddableKeywords[]

object (BiddableKeyword)

مطلوبة. قائمة الكلمات الرئيسية التي يمكن تقديم عروض أسعار لها والتي سيتم استخدامها في المجموعة الإعلانية عند إجراء التوقعات. يتطلب كلمة رئيسية واحدة على الأقل.
negativeKeywords[]

object (KeywordInfo)

تمثّل هذه السمة تفاصيل الكلمة الرئيسية. يجب تحديد كل من نص الكلمة الرئيسية ونوع المطابقة.
maxCpcBidMicros

string (int64 format)

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

BiddableKeyword

جزء كلمة رئيسية يمكن تقديم عروض أسعار لها ضمن مجموعة إعلانية.

تمثيل JSON 
{
  "keyword": {
    object (KeywordInfo)
  },
  "maxCpcBidMicros": string
}
الحقول
keyword

object (KeywordInfo)

مطلوبة. الكلمة الرئيسية. يجب أن يحتوي على نص ونوع المطابقة.
maxCpcBidMicros

string (int64 format)

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

KeywordForecastMetrics

مقاييس التوقّعات لحملة الكلمات الرئيسية غير المخطَّط لها.

تمثيل JSON 
{
  "impressions": number,
  "clickThroughRate": number,
  "averageCpcMicros": string,
  "clicks": number,
  "costMicros": string,
  "conversions": number,
  "conversionRate": number,
  "averageCpaMicros": string
}
الحقول
impressions

number

إجمالي عدد مرّات الظهور.
clickThroughRate

number

متوسط نسبة النقر إلى الظهور. لا يتوفّر إلا إذا كانت مرات الظهور أكبر من 0.
averageCpcMicros

string (int64 format)

متوسط تكلفة النقرة. لا يتوفّر هذا الخيار إلا إذا كانت النقرات أكبر من 0.
clicks

number

إجمالي عدد النقرات.
costMicros

string (int64 format)

تمثّل هذه السمة التكلفة الإجمالية.
conversions

number

العدد المتوقّع للإحالات الناجحة: النقرات * معدّل الإحالات الناجحة
conversionRate

number

معدّل الإحالات الناجحة المتوقّع
averageCpaMicros

string (int64 format)

يتم احتساب متوسط تكلفة الإجراء على أنّه CostMicros / الإحالات الناجحة.