Method: customers.recommendations.apply

يطبِّق هذا الخيار الاقتراحات المحدّدة مع مَعلمات تطبيق مقابلة.

قائمة الأخطاء الملموسة: AuthenticationError AuthorizationError DatabaseError FieldError HeaderError InternalError MutateError QuotaError RecommendationError RequestError UrlFieldError

طلب HTTP

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

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

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

المَعلمات
customerId

string

مطلوبة. رقم تعريف العميل الذي يتضمّن الاقتراح.

نص الطلب

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

تمثيل JSON 
{
  "operations": [
    {
      object (ApplyRecommendationOperation)
    }
  ],
  "partialFailure": boolean
}
الحقول
operations[]

object (ApplyRecommendationOperation)

مطلوبة. قائمة العمليات المطلوب تطبيق الاقتراحات عليها. إذا لم تكن نتائج جزئية Failure=false، فيُفترض أن تكون جميع الاقتراحات من النوع نفسه. هناك حد أقصى يبلغ 100 عملية لكل طلب.
partialFailure

boolean

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

نص الاستجابة

رسالة الرد لـ "RecommendationService.ApplyRecommendation".

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

تمثيل JSON 
{
  "results": [
    {
      object (ApplyRecommendationResult)
    }
  ],
  "partialFailureError": {
    object (Status)
  }
}
الحقول
results[]

object (ApplyRecommendationResult)

نتائج العمليات لتطبيق الاقتراحات
partialFailureError

object (Status)

الأخطاء التي تتعلّق بتعذُّر التشغيل في وضع الفشل الجزئي. لا يتم عرضه إلا عندما تكون قيمة الوسيطة الجزئية = true وتحدث جميع الأخطاء داخل العمليات. في حالة حدوث أي أخطاء خارج العمليات (على سبيل المثال، أخطاء المصادقة)، نعرض الخطأ على مستوى استدعاء إجراء عن بُعد (RPC).

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

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

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

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

ApplyRecommendationOperation

معلومات عن عملية تطبيق الاقتراح وأي مَعلمات لتخصيصه.

تمثيل JSON 
{
  "resourceName": string,

  // Union field apply_parameters can be only one of the following:
  "campaignBudget": {
    object (CampaignBudgetParameters)
  },
  "textAd": {
    object (TextAdParameters)
  },
  "keyword": {
    object (KeywordParameters)
  },
  "targetCpaOptIn": {
    object (TargetCpaOptInParameters)
  },
  "targetRoasOptIn": {
    object (TargetRoasOptInParameters)
  },
  "calloutExtension": {
    object (CalloutExtensionParameters)
  },
  "callExtension": {
    object (CallExtensionParameters)
  },
  "sitelinkExtension": {
    object (SitelinkExtensionParameters)
  },
  "moveUnusedBudget": {
    object (MoveUnusedBudgetParameters)
  },
  "responsiveSearchAd": {
    object (ResponsiveSearchAdParameters)
  },
  "useBroadMatchKeyword": {
    object (UseBroadMatchKeywordParameters)
  },
  "responsiveSearchAdAsset": {
    object (ResponsiveSearchAdAssetParameters)
  },
  "responsiveSearchAdImproveAdStrength": {
    object (ResponsiveSearchAdImproveAdStrengthParameters)
  },
  "raiseTargetCpaBidTooLow": {
    object (RaiseTargetCpaBidTooLowParameters)
  },
  "forecastingSetTargetRoas": {
    object (ForecastingSetTargetRoasParameters)
  },
  "calloutAsset": {
    object (CalloutAssetParameters)
  },
  "callAsset": {
    object (CallAssetParameters)
  },
  "sitelinkAsset": {
    object (SitelinkAssetParameters)
  },
  "raiseTargetCpa": {
    object (RaiseTargetCpaParameters)
  },
  "lowerTargetRoas": {
    object (LowerTargetRoasParameters)
  },
  "forecastingSetTargetCpa": {
    object (ForecastingSetTargetCpaParameters)
  },
  "setTargetCpa": {
    object (ForecastingSetTargetCpaParameters)
  },
  "setTargetRoas": {
    object (ForecastingSetTargetRoasParameters)
  },
  "leadFormAsset": {
    object (LeadFormAssetParameters)
  }
  // End of list of possible types for union field apply_parameters.
}
الحقول
resourceName

string

اسم مورد الاقتراح المطلوب تطبيقه.
حقل الاتحاد apply_parameters المَعلمات التي سيتم استخدامها عند تطبيق الاقتراح يمكن أن يكون الحقل "apply_parameters" واحدًا فقط مما يلي:
campaignBudget

object (CampaignBudgetParameters)

مَعلمات اختيارية يمكن استخدامها عند تطبيق اقتراح ميزانية الحملة
textAd

object (TextAdParameters)

المَعلمات الاختيارية التي يمكن استخدامها عند تطبيق اقتراح إعلان نصي
keyword

object (KeywordParameters)

مَعلمات اختيارية يمكن استخدامها عند تطبيق اقتراحات الكلمات الرئيسية
targetCpaOptIn

object (TargetCpaOptInParameters)

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

object (TargetRoasOptInParameters)

المعلَمات الاختيارية التي يمكن استخدامها عند تطبيق اقتراح تفعيل عائد الإنفاق الإعلاني المستهدف
calloutExtension

object (CalloutExtensionParameters)

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

object (CallExtensionParameters)

المعلّمات التي يتم استخدامها عند تطبيق اقتراح إضافة المكالمة.
moveUnusedBudget

object (MoveUnusedBudgetParameters)

المَعلمات المطلوب استخدامها عند تطبيق اقتراح نقل الميزانية غير المستخدَمة
responsiveSearchAd

object (ResponsiveSearchAdParameters)

المَعلمات المطلوب استخدامها عند تطبيق اقتراح إعلان متجاوب على شبكة البحث
useBroadMatchKeyword

object (UseBroadMatchKeywordParameters)

المَعلمات التي سيتم استخدامها عند تطبيق اقتراح الكلمات الرئيسية التي تستخدِم المطابقة التقريبية.
responsiveSearchAdAsset

object (ResponsiveSearchAdAssetParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح مادة عرض إعلان متجاوب على شبكة البحث
responsiveSearchAdImproveAdStrength

object (ResponsiveSearchAdImproveAdStrengthParameters)

المعلّمات التي يتم استخدامها عند تطبيق إعلان متجاوب على شبكة البحث ضمن اقتراح قوة الإعلان
raiseTargetCpaBidTooLow

object (RaiseTargetCpaBidTooLowParameters)

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

object (ForecastingSetTargetRoasParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح لعائد الإنفاق الإعلاني المستهدَف الذي تم ضبطه على مستوى التوقّعات
calloutAsset

object (CalloutAssetParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح مواد عرض وسائل الشرح.
callAsset

object (CallAssetParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح مواد عرض المكالمات.
raiseTargetCpa

object (RaiseTargetCpaParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح زيادة التكلفة المستهدفة للإجراء
lowerTargetRoas

object (LowerTargetRoasParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح عائد إنفاق إعلاني مستهدَف أقل
forecastingSetTargetCpa

object (ForecastingSetTargetCpaParameters)

المَعلمات التي يتم استخدامها عند تطبيق التوقّعات بشأن اقتراح التكلفة المستهدَفة للإجراء.
setTargetCpa

object (ForecastingSetTargetCpaParameters)

المعلّمات التي يتم استخدامها عند تطبيق اقتراح التكلفة المستهدفة للإجراء التي تم إعدادها.
setTargetRoas

object (ForecastingSetTargetRoasParameters)

المعلّمات التي يتم استخدامها عند تطبيق اقتراح عائد الإنفاق الإعلاني المستهدف المحدّد.
leadFormAsset

object (LeadFormAssetParameters)

المَعلمات التي يتم استخدامها عند تطبيق اقتراح مواد عرض نماذج العملاء المحتمَلين

CampaignBudgetParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح ميزانية الحملة

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

string (int64 format)

مبلغ ميزانية جديد مطلوب ضبطه لمورد الميزانية المستهدَفة هذا الحقل إلزامي.

TextAdParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح إعلان نصي

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

object (Ad)

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

KeywordParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح الكلمات الرئيسية

تمثيل JSON 
{
  "matchType": enum (KeywordMatchType),
  "adGroup": string,
  "cpcBidMicros": string
}
الحقول
matchType

enum (KeywordMatchType)

نوع مطابقة الكلمة الرئيسية. هذا الحقل إلزامي.
adGroup

string

مورد المجموعة الإعلانية المطلوب إضافة الكلمة الرئيسية إليه. هذا الحقل إلزامي.
cpcBidMicros

string (int64 format)

اختياري، عرض سعر النقرة لتعيينه للكلمة الرئيسية. وفي حال عدم تحديد قيمة السياسة، ستستخدِم الكلمة الرئيسية عرض السعر استنادًا إلى استراتيجية عروض الأسعار التي تستخدمها المجموعة الإعلانية المستهدفة.

TargetCpaOptInParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح التكلفة المستهدَفة للإجراء

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

string (int64 format)

متوسط تكلفة الإجراء للاستخدام في استراتيجية عروض الأسعار المستهدفة للإجراء. هذا الحقل إلزامي.
newCampaignBudgetAmountMicros

string (int64 format)

مبلغ ميزانية اختياري للحملة

TargetRoasOptInParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح تفعيل عائد الإنفاق الإعلاني المستهدَف

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

number

متوسط عائد الإنفاق الإعلاني (الأرباح لكل وحدة إنفاق) المطلوب استخدامه في استراتيجية عروض أسعار "عائد الإنفاق الإعلاني المستهدف". وتتراوح القيمة بين 0.01 و1000.0، بشكل شامل. يجب ملء هذا الحقل، ما لم يتم ضبط newCampaignBudgetAmountMicros.
newCampaignBudgetAmountMicros

string (int64 format)

مبلغ ميزانية اختياري للحملة

CalloutExtensionParameters

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

تمثيل JSON 
{
  "calloutExtensions": [
    {
      object (CalloutFeedItem)
    }
  ]
}
الحقول
calloutExtensions[]

object (CalloutFeedItem)

إضافات وسائل الشرح التي سيتم إدراجها. هذا الحقل إلزامي.

CallExtensionParameters

المعلّمات التي يتم استخدامها عند تطبيق اقتراح إضافة المكالمة.

تمثيل JSON 
{
  "callExtensions": [
    {
      object (CallFeedItem)
    }
  ]
}
الحقول
callExtensions[]

object (CallFeedItem)

سيتم إدراج إضافات المكالمات. هذا الحقل إلزامي.

SitelinkExtensionParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح روابط أقسام الموقع

تمثيل JSON 
{
  "sitelinkExtensions": [
    {
      object (SitelinkFeedItem)
    }
  ]
}
الحقول

MoveUnusedBudgetParameters

المَعلمات المطلوب استخدامها عند تطبيق اقتراح نقل الميزانية غير المستخدَمة

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

string (int64 format)

مبلغ الميزانية المطلوب الانتقال من الميزانية الزائدة إلى الميزانية المحدودة هذا الحقل إلزامي.

ResponsiveSearchAdParameters

المَعلمات المطلوب استخدامها عند تطبيق اقتراح إعلان متجاوب على شبكة البحث

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

object (Ad)

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

UseBroadMatchKeywordParameters

المَعلمات التي سيتم استخدامها عند تطبيق اقتراح الكلمات الرئيسية التي تستخدِم المطابقة التقريبية.

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

string (int64 format)

مبلغ ميزانية جديد مطلوب ضبطه لمورد الميزانية المستهدَفة

ResponsiveSearchAdAssetParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح مادة عرض إعلان متجاوب على شبكة البحث

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

object (Ad)

تم تعديل الإعلان. وسيتم استبدال محتوى الإعلان الحالي.

ResponsiveSearchAdImproveAdStrengthParameters

المعلّمات التي يتم استخدامها عند تطبيق إعلان متجاوب على شبكة البحث ضمن اقتراح قوة الإعلان

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

object (Ad)

تم تعديل الإعلان. وسيتم استبدال محتوى الإعلان الحالي.

RaiseTargetCpaBidTooLowParameters

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

تمثيل JSON 
{
  "targetMultiplier": number
}
الحقول
targetMultiplier

number

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

ForecastingSetTargetRoasParameters

المَعلمات التي سيتم استخدامها عند تطبيق اقتراح عائد إنفاق إعلاني مستهدَف على مستوى التوقّعات

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

number

عائد إنفاق إعلاني مستهدَف جديد (الإيرادات لكل وحدة إنفاق) المطلوب إعداده لمورد الحملة وتتراوح القيمة بين 0.01 و1000.0، بشكل شامل.
campaignBudgetAmountMicros

string (int64 format)

مبلغ ميزانية حملة جديد معيّن لمورد للحملة

CalloutAssetParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراحات مواد عرض وسائل الشرح

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

object (AdAssetApplyParameters)

مطلوبة. مواد عرض وسائل الشرح التي ستتم إضافتها. هذا الحقل إلزامي.

AdAssetApplyParameters

المَعلمات الشائعة المستخدَمة عند تطبيق اقتراحات مواد عرض الإعلانات

تمثيل JSON 
{
  "newAssets": [
    {
      object (Asset)
    }
  ],
  "existingAssets": [
    string
  ],
  "scope": enum (ApplyScope)
}
الحقول
newAssets[]

object (Asset)

مواد العرض المطلوب إنشاؤها وإرفاقها بنطاق. يمكن دمج هذا العنصر مع مواد العرض الحالية في المكالمة نفسها.
existingAssets[]

string

أسماء الموارد الخاصة بمواد العرض الحالية المطلوب إرفاقها بنطاق. يمكن دمج هذا العنصر مع مواد العرض الجديدة في المكالمة نفسها.
scope

enum (ApplyScope)

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

ApplyScope

النطاق الذي تريد تطبيق مواد العرض عليه.

عمليات التعداد
UNSPECIFIED لم يتم تحديد نطاق التطبيق.
UNKNOWN غير معروف.
CUSTOMER تطبيق على نطاق العميل.
CAMPAIGN طبِّق على مستوى الحملة.

CallAssetParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراحات مواد عرض المكالمات

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

object (AdAssetApplyParameters)

مطلوبة. مواد عرض المكالمات التي ستتم إضافتها. هذا الحقل إلزامي.

SitelinkAssetParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراحات مواد عرض روابط أقسام الموقع

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

object (AdAssetApplyParameters)

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

RaiseTargetCpaParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراحات زيادة التكلفة المستهدفة للإجراء

تمثيل JSON 
{
  "targetCpaMultiplier": number
}
الحقول
targetCpaMultiplier

number

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

LowerTargetRoasParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراحات بشأن عائد إنفاق إعلاني مستهدَف أقل

تمثيل JSON 
{
  "targetRoasMultiplier": number
}
الحقول
targetRoasMultiplier

number

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

ForecastingSetTargetCpaParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح محدّد للتكلفة المستهدَفة للإجراء

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

string (int64 format)

متوسط تكلفة الإجراء للاستخدام في استراتيجية عروض الأسعار المستهدفة للإجراء.
campaignBudgetAmountMicros

string (int64 format)

مبلغ ميزانية حملة جديد معيّن لمورد للحملة

LeadFormAssetParameters

المَعلمات التي يتم استخدامها عند تطبيق اقتراح لمواد عرض نموذج العملاء المحتمَلين

تمثيل JSON 
{
  "adAssetApplyParameters": {
    object (AdAssetApplyParameters)
  },
  "setSubmitLeadFormAssetCampaignGoal": boolean
}
الحقول
adAssetApplyParameters

object (AdAssetApplyParameters)

مطلوبة. مواد عرض نماذج العملاء المحتملين التي ستتم إضافتها. هذا الحقل إلزامي.
setSubmitLeadFormAssetCampaignGoal

boolean

إذا كانت القيمة صحيحة، سيتم ضبط الهدف "إرسال نموذج العملاء المحتملين" على الحملة المستهدفة. ونتيجةً لذلك، ستظهر الإعلانات كإعلانات إبداعية على شكل نماذج للعملاء المحتملين. في حال اختيار القيمة "false"، لن يتم ضبط الهدف "إرسال نموذج العملاء المحتملين" على الحملة، وستحتوي الإعلانات على مواد عرض نماذج العملاء المحتملين.

ApplyRecommendationResult

نتيجة تطبيق الاقتراح.

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

string

يُرجع التطبيق عند تطبيقه بنجاح.