שינוי

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