- طلب HTTP
- مَعلمات المسار
- نص الطلب
- نص الاستجابة
- نطاقات التفويض
- CampaignToForecast
- CriterionBidModifier
- CampaignBiddingStrategy
- ManualCpcBiddingStrategy
- MaximizeClicksBiddingStrategy
- MaximizeConversionsBiddingStrategy
- ForecastAdGroup
- BiddableKeyword
- KeywordForecastMetrics
- جرِّبه الآن
تعرض مقاييس (مثل مرات الظهور والنقرات والتكلفة الإجمالية) لتوقّعات كلمة رئيسية للحملة المحدّدة.
قائمة الأخطاء الملموسة: AuthenticationError AuthorizationError CollectionSizeError HeaderError InternalError QuotaError RequestError
طلب HTTP
POST https://googleads.googleapis.com/v16/customers/{customerId}:generateKeywordForecastMetrics
يستخدم عنوان URL بنية تحويل الترميز gRPC.
معلمات المسار
المَعلمات | |
---|---|
customerId |
رقم تعريف العميل. |
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "forecastPeriod": { object ( |
الحقول | |
---|---|
forecastPeriod |
النطاق الزمني للتوقعات. يجب أن يكون تاريخ البدء في المستقبل وأن يكون تاريخ الانتهاء في غضون عام واحد بدءًا من اليوم. المنطقة الزمنية المرجعية المستخدَمة هي المنطقة الزمنية لأحد حسابات "إعلانات Google" التي يملكها العميل. وفي حال ترك هذه السياسة بدون ضبط، سيتم استخدام نطاق زمني تلقائي يتراوح بين الأحد المقبل ويوم السبت التالي. |
campaign |
مطلوبة. الحملة المستخدَمة في التوقّعات. |
currencyCode |
العملة المستخدمة لتحويل سعر الصرف. بشكل تلقائي، يتم استخدام عملة حساب العميل. لا يجب ضبط هذا الحقل إلا إذا كانت العملة مختلفة عن عملة الحساب. يمكن العثور على قائمة رموز العملات الصالحة على الرابط https://developers.google.com/google-ads/api/data/codes-formats#currency-codes. |
نص الاستجابة
رسالة الرد بخصوص [KeywordPlanIdeaService.GenerateKeywordتوقّعMetrics].
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{
"campaignForecastMetrics": {
object ( |
الحقول | |
---|---|
campaignForecastMetrics |
نتائج توقّعات الحملة |
نطاقات التفويض
يجب توفير نطاق OAuth التالي:
https://www.googleapis.com/auth/adwords
لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.
CampaignToForecast
حملة لإنشاء توقعات لحملة الكلمات الرئيسية.
تمثيل JSON |
---|
{ "languageConstants": [ string ], "geoModifiers": [ { object ( |
الحقول | |
---|---|
languageConstants[] |
قائمة أسماء موارد اللغات المطلوب استهدافها. يكون اسم المورد بالتنسيق "languageConstants/{criterionId}". راجع https://developers.google.com/google-ads/api/data/codes-formats#languages للحصول على قائمة برموز معايير اللغة. |
geoModifiers[] |
المواقع الجغرافية المستهدَفة. يجب أن تكون المواقع الجغرافية فريدة. |
keywordPlanNetwork |
مطلوبة. الشبكة المستخدمة للاستهداف. |
negativeKeywords[] |
قائمة الكلمات الرئيسية السلبية التي سيتم استخدامها في الحملة عند إجراء التوقعات. |
biddingStrategy |
مطلوبة. استراتيجية عروض الأسعار للحملة. |
adGroups[] |
المجموعات الإعلانية في الحملة الجديدة المطلوب توقّعها. |
conversionRate |
معدل الإحالات الناجحة المتوقع (عدد الإحالات الناجحة مقسومًا على إجمالي عدد النقرات) كما حدّده المستخدم. يتم التعبير عن هذه القيمة كقيمة عشرية، لذا يجب إدخال معدل إحالة ناجحة متوقّع يبلغ 2% على النحو التالي 0.02. وفي حال ترك هذا الحقل فارغًا، سيتم استخدام معدل إحالات ناجحة مقدَّر. |
CriterionBidModifier
معدِّل عروض أسعار معيار الموقع الجغرافي.
تمثيل JSON |
---|
{ "geoTargetConstant": string, "bidModifier": number } |
الحقول | |
---|---|
geoTargetConstant |
اسم المورد للموقع الجغرافي المطلوب استهدافه يكون اسم المورد بالتنسيق "geoTargetConstants/{criterionId}". |
bidModifier |
تمثّل هذه السمة المُضاعِف المرتبط بالمعيارId. وفي حال ضبطها، لا يمكن أن تكون هذه القيمة 0. |
CampaignBiddingStrategy
استراتيجيات عروض الأسعار المتاحة لتوقعات الحملات الجديدة.
تمثيل JSON |
---|
{ // Union field |
الحقول | |
---|---|
حقل الاتحاد bidding_strategy إستراتيجيات عروض الأسعار. يمكن أن يكون الحقل "bidding_strategy " واحدًا فقط مما يلي: |
|
manualCpcBiddingStrategy |
استخدِم استراتيجية عروض أسعار النقرة اليدوية للتوقّعات. |
maximizeClicksBiddingStrategy |
استخدِم استراتيجية عروض أسعار "الحصول على الحد الأقصى من النقرات" لوضع التوقّعات. |
maximizeConversionsBiddingStrategy |
استخدِم استراتيجية عروض أسعار "تحقيق الحد الأقصى من الإحالات الناجحة" من أجل وضع التوقّعات. |
ManualCpcBiddingStrategy
استراتيجية عروض أسعار النقرة اليدوية.
تمثيل JSON |
---|
{ "maxCpcBidMicros": string, "dailyBudgetMicros": string } |
الحقول | |
---|---|
maxCpcBidMicros |
مطلوبة. عرض سعر بالمايكرو يتم تطبيقه على المجموعات الإعلانية ضمن الحملة في استراتيجية عروض أسعار "تكلفة النقرة" اليدوية. |
dailyBudgetMicros |
ميزانية على مستوى الحملة بالمايكرو. وفي حال ضبطها، يتم فرض حد أدنى لقيمة العملة المحلية المستخدَمة في الحملة. سيحدث خطأ أثناء عرض القيمة الصغرى في حال ضبط هذا الحقل على قيمة منخفضة جدًا. |
MaximizeClicksBiddingStrategy
استراتيجية عروض أسعار الحصول على الحد الأقصى من النقرات.
تمثيل JSON |
---|
{ "dailyTargetSpendMicros": string, "maxCpcBidCeilingMicros": string } |
الحقول | |
---|---|
dailyTargetSpendMicros |
مطلوبة. الإنفاق الهدف اليومي بالمايكرو والمستخدم للتقدير. يتم فرض حد أدنى لقيمة العملة المحلية المستخدَمة في الحملة. سيحدث خطأ أثناء عرض القيمة الصغرى في حال ضبط هذا الحقل على قيمة منخفضة جدًا. |
maxCpcBidCeilingMicros |
الحد الأقصى لعروض الأسعار القصوى للنقرة بالمايكرو. |
MaximizeConversionsBiddingStrategy
استراتيجية عروض أسعار "تحقيق الحد الأقصى من الإحالات الناجحة".
تمثيل JSON |
---|
{ "dailyTargetSpendMicros": string } |
الحقول | |
---|---|
dailyTargetSpendMicros |
مطلوبة. الإنفاق الهدف اليومي بالمايكرو والمستخدم للتقدير. يجب أن تكون هذه القيمة أكبر من صفر. |
ForecastAdGroup
المجموعة الإعلانية التي تشكّل جزءًا من حملة يمكن وضع توقّعات لها.
تمثيل JSON |
---|
{ "biddableKeywords": [ { object ( |
الحقول | |
---|---|
biddableKeywords[] |
مطلوبة. قائمة الكلمات الرئيسية التي يمكن تقديم عروض أسعار لها والتي سيتم استخدامها في المجموعة الإعلانية عند إجراء التوقعات. يتطلب كلمة رئيسية واحدة على الأقل. |
negativeKeywords[] |
تمثّل هذه السمة تفاصيل الكلمة الرئيسية. يجب تحديد كل من نص الكلمة الرئيسية ونوع المطابقة. |
maxCpcBidMicros |
التكلفة القصوى للنقرة المطلوب استخدامها للمجموعة الإعلانية عند إنشاء زيارات متوقعة. ستلغي هذه القيمة قيمة التكلفة القصوى للنقرة التي تم تحديدها في استراتيجية عروض الأسعار. حدِّد هذا الحقل فقط لاستراتيجيات عروض الأسعار التي تستخدِم قيم التكلفة القصوى للنقرة. |
BiddableKeyword
جزء كلمة رئيسية يمكن تقديم عروض أسعار لها ضمن مجموعة إعلانية.
تمثيل JSON |
---|
{
"keyword": {
object ( |
الحقول | |
---|---|
keyword |
مطلوبة. الكلمة الرئيسية. يجب أن يحتوي على نص ونوع المطابقة. |
maxCpcBidMicros |
عرض سعر أقصى للنقرة بوحدات المايكرو يتجاوز عرض السعر الأقصى للنقرة على مستوى المجموعة الإعلانية في محاكاة التوقعات. ستلغي هذه القيمة قيمة التكلفة القصوى للنقرة التي تم تحديدها في استراتيجية عروض الأسعار والمجموعة الإعلانية. حدّد هذا الحقل فقط لاستراتيجيات عروض الأسعار التي تسمح بقيم التكلفة القصوى للنقرة. |
KeywordForecastMetrics
مقاييس التوقّعات لحملة الكلمات الرئيسية غير المخطَّط لها.
تمثيل JSON |
---|
{ "impressions": number, "clickThroughRate": number, "averageCpcMicros": string, "clicks": number, "costMicros": string, "conversions": number, "conversionRate": number, "averageCpaMicros": string } |
الحقول | |
---|---|
impressions |
إجمالي عدد مرّات الظهور. |
clickThroughRate |
متوسط نسبة النقر إلى الظهور. لا يتوفّر إلا إذا كانت مرات الظهور أكبر من 0. |
averageCpcMicros |
متوسط تكلفة النقرة. لا يتوفّر هذا الخيار إلا إذا كانت النقرات أكبر من 0. |
clicks |
إجمالي عدد النقرات. |
costMicros |
تمثّل هذه السمة التكلفة الإجمالية. |
conversions |
العدد المتوقّع للإحالات الناجحة: النقرات * معدّل الإحالات الناجحة |
conversionRate |
معدّل الإحالات الناجحة المتوقّع |
averageCpaMicros |
يتم احتساب متوسط تكلفة الإجراء على أنّه CostMicros / الإحالات الناجحة. |