يتم تعديل معظم الموارد (إنشاؤها أو تعديلها أو إزالتها) باستخدام الطريقة Mutate
. يتم استدعاء طريقة Mutate
باعتبارها POST
HTTP إلى عنوان URL خاص بالمورد يطابق نمط اسم المورد، بدون معرّف المورد اللاحق.
وبدلاً من ذلك، تُرسَل أرقام تعريف الموارد المطلوب تغييرها في نص طلب JSON. يتيح لك هذا إرسال طلب بيانات واحد من واجهة برمجة التطبيقات يحتوي على عمليات متعددة على موارد مختلفة.
على سبيل المثال، يستخدم اسم مورد الحملة التنسيق التالي:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
لاستنتاج عنوان URL المستخدَم في الحملات المتغيرة، احذف رقم تعريف المورد اللاحقة وألحِق القيمة :mutate
:
https://googleads.googleapis.com/v17/customers/CUSTOMER_ID/campaigns:mutate
تتضمّن رسالة Mutate
كائن JSON من المستوى الأعلى مع مصفوفة operations
يمكن أن تحتوي على العديد من كائنات operation
. ويمكن أن تكون كل عملية بدورها واحدة مما يلي: create
أو update
أو remove
. هذه هي عمليات التغيير
الوحيدة.
POST /v17/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
لتغيير هذا السلوك. يُرجى الاطّلاع على Mutate resources للحصول على معلومات أكثر تفصيلاً عن دلالات عملية التغيير.
إنشاء
ينتج عن إنشاء العمليات كيانات جديدة ويجب أن تتضمن تمثيل JSON كاملاً للمورد الذي تنوي إنشاءه.
POST /v17/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 /v17/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 /v17/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" } ] }