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

وفقًا لما نوقش في دليل بنية واجهة برمجة التطبيقات، يكون لكل مورد في المستوى الأعلى في 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 (pause)

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

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