שינוי

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

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

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

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