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

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

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

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

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

• 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