Method: customers.generateKeywordForecastMetrics

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

قائمة الأخطاء التي تظهر: AuthenticationError AuthorizationError CollectionSizeError HeaderError InternalError QuotaError RequestError

طلب HTTP

POST https://googleads.googleapis.com/v14/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

المُضاعِف المرتبط لمعرّف المعيار. وفي حال ضبطها، لا يمكن أن تكون هذه القيمة 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 / الإحالات الناجحة.