اکثر منابع با استفاده از روش Mutate اصلاح می شوند (ایجاد، به روز یا حذف می شوند). متد Mutate به عنوان یک HTTP POST به یک URL خاص منبع که با الگوی نام منبع مطابقت دارد، بدون شناسه منبع دنباله‌ای فراخوانی می‌شود. شناسه‌های منابعی که باید جهش داده شوند در بدنه درخواست JSON ارسال می‌شوند. این به شما امکان می‌دهد یک تماس API که شامل چندین عملیات در منابع مختلف است ارسال کنید.
به عنوان مثال، نام منبع یک کمپین از قالب زیر استفاده می کند:
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": [
...
]
}
اکثر سرویس ها هزاران عملیات را در یک تماس API پشتیبانی می کنند. راهنمای محدودیت های سیستم محدودیت های اندازه درخواست را مستند می کند.
عملیات در یک درخواست API منفرد به صورت پیش‌فرض به‌عنوان یک مجموعه از اقدامات اجرا می‌شوند، به این معنی که یا همه با هم موفق می‌شوند یا در صورت شکست هر یک از عملیات، کل دسته با شکست مواجه می‌شوند. برخی از سرویس‌ها از ویژگی partialFailure برای تغییر این رفتار پشتیبانی می‌کنند. برای اطلاعات دقیق تر در مورد معنایی عملیات جهش، به منابع جهش مراجعه کنید.
ایجاد کنید
عملیات ایجاد موجودیت‌های جدیدی را تولید می‌کند و باید شامل یک نمایش کامل 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 از یک شی داشته باشید (به عنوان مثال، همانطور که توسط یک فراخوان API قبلی برگردانده شده است)، اما فقط می خواهید فیلدهای خاصی را تغییر دهید. به جای هرس کردن شی 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 Ads آن را روی 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"
}
]
}