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

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

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

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

تغيير العناصر

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

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

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

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

العمليات

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

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 (ميزة متوقّفة نهائيًا)

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

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