שינוי

רוב המשאבים משתנים (נוצרים, מתעדכנים או מוסרים) באמצעות שיטת Mutate. השיטה Mutate מופעלת כ-POST של HTTP לכתובת URL ספציפית למשאב שתואמת לדפוס של שם המשאב, ללא מזהה המשאב שבסוף. במקום זאת, מזהי המשאבים שרוצים לבצע בהם מוטציה נשלחים בגוף הבקשה ב-JSON. כך אפשר לשלוח קריאה יחידה ל-API שמכילה כמה פעולות במשאבים שונים.

לדוגמה, שם המשאב של קמפיין מופיע בפורמט הבא:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

כדי לקבל את כתובת ה-URL שמשמש לשינוי של קמפיינים, משמיטים את מזהה המשאב שבסוף ומצרפים את הערך :mutate:

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

הודעה מסוג Mutate מכילה אובייקט JSON ברמה העליונה עם מערך operations שיכול להכיל הרבה אובייקטים מסוג operation. כל פעולה יכולה להיות אחת מ-create,‏ update או remove. אלה הפעולות האפשריות היחידה לשינוי.

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