שינוי

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

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

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

• עיצוב ממשק REST
• שמות המשאבים
• מיפויים של 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 מותאם אישית בסקריפט כדי ליצור אובייקט מתאים.

לחלופין, אתם יכולים לנסות ליצור פעולה באופן דינמי באמצעות התכונה "רוצה לנסות?" של תקציב הקמפיין, שמאפשרת ליצור גוף בקשה באופן דינמי על ידי בחירת השדות שרוצים להוסיף. אחר כך אפשר לחלץ את תוכן הפעולה מהתוצאה שנוצרה ולהוסיף אותו לקריאה ל-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 נעשה שימוש ב-lowerCamelCase. שני המקרים האלה מקובלים בסקריפטים של Google Ads, כך שאפשר להעתיק קוד ישירות מהמדריך הזה.

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

• ‫apiVersion: אפשר לציין גרסת API מותאמת אישית, כמו V26, אם רוצים להשתמש בגרסה שונה מזו שמוגדרת כברירת מחדל בסקריפטים. אתם יכולים להשתמש בכל גרסה שזמינה לציבור באותו זמן.
• 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});