تبديل

يتم تعديل معظم الموارد (إنشائها أو تحديثها أو إزالتها) باستخدام طريقة Mutate. يتم استدعاء الإجراء Mutate باعتباره HTTP POST إلى عنوان URL خاص بمورد يتطابق مع نمط اسم المورد، بدون معرّف المورد اللاحق. وبدلاً من ذلك، يتم إرسال معرّفات الموارد المراد تغييرها في نص طلب JSON. يتيح لك ذلك إرسال طلب بيانات واحد من واجهة برمجة التطبيقات يحتوي على عمليات متعددة على موارد مختلفة.

على سبيل المثال، يستخدِم اسم مورد الحملة التنسيق التالي:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

للحصول على عنوان URL المستخدَم لتغيير الحملات، احذف رقم تعريف المورد اللاحق وأضِف :mutate:

https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/campaigns:mutate

تحتوي رسالة Mutate على عنصر JSON من المستوى الأعلى مع مصفوفة operations يمكن أن تحتوي على العديد من عناصر operation. يمكن أن تكون كل عملية بدورها واحدة مما يلي: create أو update أو remove. هذه هي عمليات التغيير الوحيدة المحتملة.

POST /v16/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 /v16/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 /v16/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 /v16/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"
    }
  ]
}