שינוי

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

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