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

كما هو موضّح في دليل بنية واجهة برمجة التطبيقات، تتوفّر لكل مورد من المستوى الأعلى في 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 أو عدِّل الموارد.

استجابات التغيير

تعتمد البيانات المعروضة في الاستجابة على البيانات التي تم إرسالها في الـ 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.