שינוי

סקריפטים של Google Ads תומכים בשינויים גנריים שזמינים ב-Google Ads API. אפשר לבצע ב-Google Ads Scripts את רוב הפעולות שאפשר לבצע ב-GoogleAdsService.mutate, כולל יצירה וניהול של קמפיינים.

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

ריכזנו כאן כמה משאבים בסיסיים בנושא ממשק REST של Google Ads API שכדאי להכיר לפני שממשיכים לקרוא את המדריך הזה:

• REST Interface Design
• שמות משאבים
• מיפויים של JSON
• Mutate

דוגמה בסיסית

כדי להדגים את הפונקציונליות, נשתמש בדוגמה הבסיסית הזו ליצירת תקציב לקמפיין:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

קריאה ל-AdsApp.mutate מקבלת אובייקט JSON שמייצג MutateOperation יחיד. באובייקט הזה מציינים את סוג הפעולה שמבצעים – במקרה הזה, campaignBudgetOperation. לאחר מכן מציינים create, remove או את שניהם, update ו-updateMask. השדות הספציפיים בתוך create ו-update תלויים בסוג המשאב הספציפי שעליו מבוצעת הפעולה.

הרכבת פעולה

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

לחלופין, אפשר לנסות ליצור פעולה באופן דינמי באמצעות התכונה Try this (נסה את זה) לתקציב הקמפיין, שמאפשרת ליצור גוף בקשה באופן דינמי על ידי בחירה של השדות שרוצים להוסיף. לאחר מכן תוכלו לחלץ את תוכן הפעולה מהתוצאה שנוצרה ולהוסיף אותו לקריאה mutate אחרי שתציינו את סוג הפעולה.

סוגי פעולות

יצירה

מציינים create בפעולה ומעבירים ייצוג אובייקט של המשאב שרוצים ליצור.

למעלה יש דוגמה לפעולה create.

הסרה

מציינים remove בפעולה ומעבירים את שם המשאב של המשאב שרוצים להסיר, לדוגמה:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

אם לא ידוע לכם שם המשאב של ישות מסוימת, תוכלו לאחזר אותו באמצעות בקשת Adsapp.search.

עדכון

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

דוגמה לפעולת update:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

טיפול בתוצאות

ללא קשר לסוג הפעולה, ערך ההחזרה הוא MutateResult. אפשר להשתמש בשם המשאב שמוחזר כדי לשלוח שאילתה לגבי המצב הנוכחי של המשאב אחרי השינוי, ולבדוק אם הפעולה הצליחה או אילו שגיאות התרחשו, אם בכלל.

דוגמה לזרימה בסיסית של בדיקת תוצאה והדפסת מידע מסוים ביומנים:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

פעולות מרובות

סקריפטים של Google Ads תומכים גם בשינוי של כמה פעולות בבקשה אחת באמצעות השיטה AdsApp.mutateAll. אפשר ליצור ישויות שתלויות זו בזו, כמו היררכיה מלאה של קמפיין, בבקשה אחת. אפשר גם להגדיר את כל הפעולות כפעולות אטומיות, כך שאם אחת מהן תיכשל, אף אחת מהן לא תתבצע.

ערך ההחזרה הוא מערך של אובייקטים MutateResult, אחד לכל פעולה שציינתם ובאותו סדר של הפעולות הראשוניות.

התכונה הזו פועלת כמו התכונה ב-Google Ads API, ולכן מומלץ לעיין במדריך שיטות מומלצות לשימוש ב-Google Ads API כדי לקבל הסבר מלא על מזהים זמניים ושיקולים נוספים. שימו לב שבמדריך הזה נעשה שימוש בסימן snake_case כדי לייצג שמות של שדות, ואילו במסמכי התיעוד של Google Ads Scripts נעשה שימוש בסימן lowerCamelCase. שני המקרים האלה מתקבלים בסקריפטים של Google Ads, כך שאפשר להעתיק קוד ישירות מהמדריך הזה.

כדי לבצע כמה פעולות בבקשה אחת, אוספים את כל הפעולות במערך ואז קוראים ל-AdsApp.mutateAll. הקריאה mutateAll מקבלת את מערך הפעולות כארגומנט ראשון, וארגומנט שני אופציונלי של אפשרויות, כולל:

• ‫apiVersion: אפשר לציין גרסת API מותאמת אישית, כמו V20, אם רוצים להשתמש בגרסה שונה מגרסת ברירת המחדל של הסקריפטים. אתם יכולים להשתמש בכל גרסה שזמינה לציבור באותו זמן.
• partialFailure: ברירת המחדל של השדה הזה היא true. אם הערך מוגדר ל-true, הפעולות התקינות יבוצעו והפעולות שנכשלו יחזירו שגיאות. אם המדיניות מוגדרת כ-false, ואחת מהפעולות נכשלת, לא מתבצעות פעולות נוספות, כך שקבוצת הפעולות הזו היא אטומית.

הנה דוגמה עם כמה פעולות שיוצרות תקציב לקמפיין, קמפיין וקבוצת מודעות בבקשה אטומית.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});