Method: customers.googleAds.mutate

تُنشئ هذه الوظيفة الموارد أو تعدّلها أو تزيلها. تتيح هذه الطريقة إجراء معاملات ذرية مع أنواع متعدّدة من الموارد. على سبيل المثال، يمكنك إنشاء حملة وميزانية حملة بشكلٍ آلي، أو إجراء ما يصل إلى آلاف عمليات التعديل بشكلٍ آلي.

هذه الطريقة هي في الأساس غلاف حول سلسلة من طرق التعديل. الميزات الوحيدة التي يوفّرها هذا الإجراء مقارنةً باستدعاء هذه الطرق مباشرةً هي:

  • المعاملات الذرية
  • أسماء الموارد المؤقتة (الموضّحة أدناه)
  • انخفاض وقت الاستجابة إلى حدّ ما عند إجراء سلسلة من طلبات التعديل

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

مزايا المعاملات الذرية

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

أسماء الموارد المؤقتة

أسماء الموارد المؤقتة هي نوع خاص من أسماء الموارد المستخدَمة لإنشاء مورد والإشارة إلى هذا المورد في الطلب نفسه. على سبيل المثال، إذا تمّ إنشاء ميزانية حملة باستخدام resourceName يساوي customers/123/campaignBudgets/-1، يمكن إعادة استخدام اسم المورد هذا في حقل Campaign.budget في الطلب نفسه. بهذه الطريقة، يتم إنشاء الموردَين وربطهما بشكلٍ ذري.

لإنشاء اسم مورد مؤقت، ضَع رقمًا سالبًا في جزء الاسم الذي سيخصّصه الخادم عادةً.

ملاحظة:

  • يجب إنشاء الموارد باستخدام اسم مؤقت قبل أن تتم إعادة استخدام الاسم. على سبيل المثال، سيتعذّر تنفيذ المثال السابق CampaignBudget+Campaign في حال عكس ترتيب التحويل.
  • لا يتم تذكُّر الأسماء المؤقتة في جميع الطلبات.
  • ما مِن حدّ أقصى لعدد الأسماء المؤقتة في الطلب.
  • يجب أن يستخدم كل اسم مؤقت رقمًا سالبًا فريدًا، حتى إذا اختلفت أنواع الموارد.

استغرق الرد وقتًا طويلاً

من المهم تجميع عمليات التحويل حسب نوع المورد، وإلا قد تنتهي مهلة الطلب ويتعذّر إكماله. ويتساوى وقت الاستجابة تقريبًا مع سلسلة من طلبات البيانات إلى طرق فردية لتغيير البيانات، حيث يكون كل تغيير في نوع المورد طلبًا جديدًا. على سبيل المثال، يُعدّ تغيير 10 حملات ثم 10 مجموعات إعلانية مثل إجراء طلبَين، في حين أنّ تغيير حملة واحدة ومجموعة إعلانية واحدة وحملة واحدة ومجموعة إعلانية واحدة يُعدّ مثل إجراء 4 طلبات.

قائمة بالأخطاء التي تمّ طرحها: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

طلب HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

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

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

المعلمات
customerId

string

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

نص الطلب

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

تمثيل JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
الحقول
mutateOperations[]

object (MutateOperation)

مطلوب. قائمة العمليات التي يجب تنفيذها على موارد فردية
partialFailure

boolean

إذا كانت القيمة صحيحة، سيتم تنفيذ العمليات الناجحة وستؤدي العمليات غير الصالحة إلى ظهور أخطاء. إذا كانت القيمة false، سيتم تنفيذ جميع العمليات في معاملة واحدة إذا كانت جميعها صالحة فقط. القيمة التلقائية هي false.
validateOnly

boolean

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

enum (ResponseContentType)

إعداد نوع محتوى الردّ لتحديد ما إذا كان يجب إرجاع المورد القابل للتغيير أو اسم المورد فقط بعد إجراء عملية التحويل. لن يتم عرض المورد القابل للتغيير إلا إذا كان يحتوي على حقل الاستجابة المناسب. على سبيل المثال، MutateCampaignResult.campaign.

نص الاستجابة

رسالة الردّ بشأن GoogleAdsService.Mutate

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

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

object (Status)

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

object (MutateOperationResponse)

جميع الردود على عملية التحويل.

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

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على OAuth 2.0 Overview.