שינוי

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

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

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

• עיצוב ממשק REST
• שמות משאבים
• מיפויי JSON
• שינוי

דוגמה בסיסית

כדי להדגים את הפונקציונליות, אפשר להדגים את הדוגמה הבסיסית הבאה, שיוצרת תקציב לקמפיין:

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 מותאמת אישית, כמו V16. אפשר להשתמש בכל גרסה שגלויה לכולם באותו זמן.
• 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});