تبديل

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

لاستخلاص عنوان URL المستخدَم لتعديل الحملات، عليك حذف رقم تعريف المورد في النهاية وإضافة :mutate:

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

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

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