تبديل

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

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

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

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

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