שינוי

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

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

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

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

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

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