جهش

بیشتر منابع بااستفاده از Mutate روش اصلاح می‌شوند (ایجاد، به‌روزرسانی، یا برداشته می‌شوند). روش Mutate به‌عنوان POST HTTP برای نشانی وب مختص منبعی که با الگوی نام منبع مطابقت دارد، بدون شناسه منبع انتهایی، فراخوانی می‌شود. شناسه‌های منابعی که باید تغییر کنند در بدنه درخواست JSON ارسال می‌شوند. این به شما امکان می‌دهد یک فراخوانی API تکی ارسال کنید که حاوی چندین عملیات روی منابع مختلف است.

برای مثال، نام منبع پویش از قالب زیر استفاده می‌کند:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

برای به‌دست آوردن نشانی وب مورداستفاده برای پویش‌های تغییردهنده، شناسه منبع انتهایی را حذف کنید و :mutate را اضافه کنید:

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

پیام Mutate حاوی شیء JSON سطح بالا با آرایه operations است که می‌تواند حاوی اشیای operation زیادی باشد. هر عملیات، به نوبه خود، می‌تواند یکی از این موارد باشد: create، update، یا remove. این‌ها تنها عملیات جهش ممکن هستند.

POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

{
  "operations": [
    ...
  ]
}

اکثر سرویس‌ها از هزاران عملیات در یک فراخوانی API پشتیبانی می‌کنند. راهنمای محدودیت‌های سیستم محدودیت‌های مربوط به اندازه‌های درخواست را مستند می‌کند.

عملیات درون یک درخواست میانای برنامه‌سازی کاربردی به‌طور پیش‌فرض به‌عنوان یک مجموعه کنش اجرا می‌شود، یعنی یا همه باهم موفق می‌شوند یا اگر هر عملیات تکی ناموفق باشد، کل دسته ناموفق می‌شود. برخی‌از سرویس‌ها از partialFailure مشخصه برای تغییر این رفتار پشتیبانی می‌کنند. برای اطلاعات دقیق‌تر درباره معناشناسی عملیات جهش، منابع جهش را ببینید.

ایجاد کردن

عملیات ایجاد، نهادهای جدیدی تولید می‌کند و باید شامل نمایش JSON کامل منبعی باشد که قصد ایجاد آن را دارید.

POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_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 /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

{
  "operations": [
    {
      "updateMask": "name,status",
      "update": {
        "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID",
        "name": "My renamed campaign",
        "status": "PAUSED",
      }
    }
  ]
}

برداشتن

عملیات برداشتن به‌طور مؤثر شیء را حذف می‌کند و وضعیت Google Ads آن را روی REMOVED تنظیم می‌کند. فقط resourceName که باید برداشته شود لازم است.

POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN

{
  "operations": [
    {
      "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID"
    }
  ]
}