שינוי

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

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

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

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

POST /v25/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. במדריך System Limits מפורטות המגבלות על גודל הבקשות.

כברירת מחדל, פעולות בבקשת API יחידה מבוצעות כקבוצה אחת של פעולות, כלומר כולן מצליחות יחד או שכל הבקשה נכשלת אם פעולה אחת נכשלת. חלק מהשירותים תומכים במאפיין partialFailure כדי לשנות את ההתנהגות הזו. מידע נוסף על הסמנטיקה של פעולות שינוי זמין במאמר שינוי משאבים.

יצירה

פעולות יצירה יוצרות ישויות חדשות וחייבות לכלול ייצוג מלא של משאב ה-JSON שרוצים ליצור.

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