שינוי

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

התכונה הזו מאפשרת גישה לחלק גדול מאוד של 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});