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

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

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

طلبات التغيير

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

• ‫customer_id (أو customerId في عناوين URL لـ REST)
• مجموعة من operations
• إعدادات التنفيذ الاختيارية، مثل partial_failure وvalidate_only وresponse_content_type (التي تحدّد ما إذا كان سيتم عرض المورد القابل للتغيير أو اسم المورد فقط بعد التغيير)

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

• customer_id
• مجموعة من CampaignOperation عنصر (operations)
• إعدادات التنفيذ الاختيارية (partial_failure وvalidate_only وresponse_content_type تشير إلى نوع الردّ المفضّل)

العمليات

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

create

تنشئ هذه الطريقة نسخة جديدة من المرجع.

update

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

remove

تزيل هذه الطريقة المورد المحدّد من خلال سلسلة اسم المورد (على سبيل المثال، customers/1234567890/campaigns/987654321).

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

عمليات مجمعة

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

على سبيل المثال، إذا أردت إنشاء عشر حملات، عليك إرسال MutateCampaignsRequest واحد يحتوي على عشرة عناصر CampaignOperation. لتجميع العمليات على مستوى أنواع الموارد المختلفة في طلب واحد، استخدِم GoogleAdsService.Mutate أو الموارد المتغيّرة.

ردود Mutate

تعتمد البيانات التي يتم عرضها في الاستجابة على ما تم إرساله في الحقل response_content_type لطلب التغيير. على سبيل المثال، في حال تحديد MUTABLE_RESOURCE، سيتضمّن الردّ كلاً من resource_name للمورد والحقول القابلة للتغيير للحملة في campaign. بشكل تلقائي (RESOURCE_NAME_ONLY)، تتم تعبئة resource_name فقط في كل MutateCampaignResult.

أخطاء التغيير

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

تتبُّع التغييرات

لتتبُّع التغييرات التي تم إجراؤها على العناصر في حسابك على "إعلانات Google" أو لاسترداد الحالة الحالية للعناصر، يمكنك استخدام الموردَين change_status وchange_event.

• يوفّر change_status ملخّصًا للموارد التي تم تغييرها خلال فترة زمنية معيّنة.
• يوفّر change_event سجلّاً مفصّلاً للتغييرات، بما في ذلك القيم القديمة والجديدة للحقول التي تم تغييرها.

للاستعلام عن هذه الموارد، استخدِم طريقة GoogleAdsService.SearchStream أو GoogleAdsService.Search. مزيد من المعلومات عن بثّ التقارير باستخدام GoogleAdsService