يتم تعديل معظم الموارد (إنشاؤها أو تعديلها أو إزالتها) باستخدام Mutateطريقة. يتم استدعاء طريقة Mutate كطلب HTTP POST إلى عنوان URL خاص بمورد يتطابق مع نمط اسم المورد، بدون رقم تعريف المورد اللاحق.
بدلاً من ذلك، يتم إرسال أرقام تعريف الموارد المطلوب تعديلها في نص طلب JSON. يتيح لك ذلك إرسال طلب واحد إلى واجهة برمجة التطبيقات يتضمّن عمليات متعددة على موارد مختلفة.
على سبيل المثال، يستخدم اسم مرجع الحملة التنسيق التالي:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
لاستخلاص عنوان URL المستخدَم لتعديل الحملات، احذف رقم تعريف المورد اللاحق وأضِف :mutate:
https://googleads.googleapis.com/v22/customers/CUSTOMER_ID/campaigns:mutate
تحتوي رسالة Mutate على عنصر JSON من المستوى الأعلى مع مصفوفة operations يمكن أن تحتوي على العديد من عناصر operation. ويمكن أن تكون كل عملية من العمليات التالية: create أو update أو remove. هذه هي عمليات التعديل الممكنة فقط.
POST /v22/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ ... ] }
تتيح معظم الخدمات تنفيذ آلاف العمليات في طلب واحد من واجهة برمجة التطبيقات. يوضّح دليل حدود النظام القيود المفروضة على أحجام الطلبات.
يتم تنفيذ العمليات ضِمن طلب بيانات واحد من واجهة برمجة التطبيقات كمجموعة واحدة من الإجراءات تلقائيًا، ما يعني أنّها إما تنجح كلها معًا أو تفشل المجموعة بأكملها إذا تعذّر تنفيذ أي عملية واحدة. تتيح بعض الخدمات استخدام السمة
partialFailure لتغيير هذا السلوك. اطّلِع على تعديل الموارد
للحصول على مزيد من التفاصيل حول دلالات عملية التعديل.
إنشاء
تنتج عمليات الإنشاء كيانات جديدة ويجب أن تتضمّن تمثيلاً كاملاً بتنسيق JSON للمورد الذي تريد إنشاءه.
POST /v22/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "create": { "name": "An example campaign", "status": "PAUSED", "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID", "advertisingChannelType": "SEARCH", "networkSettings": { "targetGoogleSearch": true, "targetSearchNetwork": true, "targetContentNetwork": true, "targetPartnerSearchNetwork": false }, "target_spend": {} } } ] }
تعديل
تُجري عمليات التعديل تعديلات متفرقة على مورد حالي. ما عليك سوى تحديد الحقول التي تريد تعديلها.
لتحديد الحقول التي تريد تعديلها، اضبط السمة updateMask على قائمة بأسماء الحقول مفصولة بفواصل. ويكون ذلك مفيدًا بشكل خاص إذا كان لديك تمثيل JSON مكتمل لعنصر (على سبيل المثال، كما تم عرضه من خلال طلب سابق من واجهة برمجة التطبيقات)، ولكنك تريد تغيير حقول معيّنة فقط.
بدلاً من حذف بعض الحقول من عنصر JSON، يمكنك إدراج أسماء الحقول التي تريد تعديلها في updateMask وإرسال عنصر JSON بالكامل.
يغيّر المثال أدناه name وstatus لحملة حالية لها resourceName المحدّد.
POST /v22/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
إزالة
تؤدي عمليات الإزالة إلى حذف عنصر بشكل فعّال، مع ضبط حالته في "إعلانات Google" على REMOVED. يجب توفير resourceName المطلوب إزالته فقط.
POST /v22/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }