تغيير العناصر وفحصها

الهدف: فهم كيفية تعديل العناصر وفحصها باستخدام Google Ads API

وفقًا لما نوقش في دليل بنية واجهة برمجة التطبيقات، يكون لكل مورد من المستوى الأعلى في Google Ads API خدمة مقابلة خاصة بنوع الموارد تتوافق مع:

• تعديل أمثلة المورد
• استرداد مثيل واحد من المورد للفحص

سيستخدم هذا الدليل CampaignService لتوضيح تعديل كائنات Campaign وفحصها، ولكن تنطبق المفاهيم نفسها على جميع الخدمات الخاصة بأنواع الموارد.

العبارة الرئيسية: المورد ذو المستوى الأعلى هو مورد لا يتضمن اسمه نقطة (.). على سبيل المثال، Campaign مورد من المستوى الأعلى، ولكن Campaign.NetworkSettings ليس كذلك.

تغيير الكائنات

سيكون لكل خدمة خاصة بنوع مورد طريقة mutate التي تقبل طلب التغيير. يتألف هذا الطلب من:

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

على سبيل المثال، تقبل طريقة MutateCampaigns في CampaignService السمة MutateCampaignsRequest التي تتكوّن مما يلي:

• customerId
• مجموعة من CampaignOperation من العناصر
• الحقل response_content_type الذي يشير إلى نوع الردّ المفضّل

العمليات

يتيح لك كائن عملية مثل CampaignOperation تحديد الإجراء الذي تريد تنفيذه على مورد واحد من خلال ضبط حقل operation الخاص به. هذا الحقل هو حقل واحد يتألّف من السمات التالية التي يكون نوعها هو نوع المورد:

create

إنشاء مثيل جديد للمورد.

update

عدِّل المورد لمطابقة سمات المورد update. عند ضبط هذا الحقل، يجب أيضًا إعداد update_mask للعملية، والتي تُعلِم Google Ads API بالسمات التي يجب تعديلها أثناء عملية التحديث. تتضمّن كل مكتبة برامج طريقة مساعدة أو طريقة مساعِدة ستنشئ update_mask لك، كما هو موضّح في مكتبات العملاء.

remove

إزالة المورد.

بما أنّ الحقل operation هو حقل oneof، لا يمكنك استخدام عملية واحدة لتعديل عناصر متعدّدة. على سبيل المثال، إذا أردت إنشاء حملة واحدة وإزالة حملة أخرى، أضِف مثيلَين من CampaignOperation إلى طلبك: مثيل مع مجموعة create والثانية بمجموعة remove.

عمليات التجميع

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

مثلاً، إذا أردت إنشاء عشر حملات، يجب إرسال MutateCampaignsRequest واحدة تحتوي على عشرة عناصر CampaignOperation.

تغيير الردود

يعتمد ما يتم عرضه في الردّ على ما تم إرساله في response_content_type لطلب التبديل. على سبيل المثال، إذا تم تحديد MUTABLE_RESOURCE، لن يحتوي الرد إلا على الحقول القابلة للتغيير في الحملة. يمكنك بعد ذلك إجراء عمليات تغيير للمتابعة على كائن المورد هذا دون الحاجة إلى إعادة إنشائه.

أخطاء التبديل

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

تحذير: لم يعد get متاحًا. استخدِم search أو searchStream لاسترداد العناصر بدلاً من ذلك.

فحص العناصر التي تتضمّن الأمر get (متوقّف نهائيًا)

وبالإضافة إلى تغيير الكائنات، تشتمل كل خدمة خاصة بنوع المورد أيضًا على طريقة get لاسترداد جميع سمات مورد واحد. تقبل هذه الطريقة طلب الحصول على (Get) الذي تكون السمة الوحيدة له هي resource_name.

نقطة رئيسية: استخدِم السمة get باعتدال.

تعتبر طرق الحصول على البيانات هي الراحة التي توفرها Google Ads API لتسهيل استرداد جميع سمات عنصر واحد. على الرغم من أنّ هذه الأداة رائعة للتعرّف على واجهة برمجة التطبيقات أو فحص عنصر فردي من أجل تصحيح الأخطاء أو الأغراض التعليمية، يجب ألا يستخدم تطبيقك طرق الحصول على القيم لاسترداد الكائنات لمعالجتها أو إعداد تقارير عنها. بدلاً من ذلك، استخدِم GoogleAdsService، بما أنّه يتيح لك استرداد سمات معيّنة فقط للكائنات، ويتيح استرداد مقاييس الأداء، كما يسمح ببث المحتوى عبر مجموعات كبيرة من النتائج. إذا أرسل تطبيقك عددًا كبيرًا من طلبات تلقّي الرسائل، قد تواجه حدودًا لمعدّل الزحف.