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

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

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

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

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

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

ستتضمّن كل خدمة خاصة بنوع مورد معيّن طريقة 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" إلا إذا نجحت كل عملية في الطلب. اطّلِع على دليل الأخطاء الشائعة للحصول على قائمة بالأخطاء الشائعة وكيفية حلّها.