שינוי

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

כדי להפיק את כתובת ה-URL שמשמשת לשינוי קמפיינים, משמיטים את מזהה המשאב בסוף ומוסיפים :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. במדריך מגבלות המערכת מפורטות המגבלות על גודל הבקשות.

כברירת מחדל, פעולות בבקשת 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 (למשל, כפי שהוחזר על ידי קריאה קודמת ל-API), אבל אתם רוצים לשנות רק שדות מסוימים. במקום להסיר חלקים מאובייקט ה-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"
    }
  ]
}