שינוי

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

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

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

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

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