אחת התכונות החזקות של סקריפטים של Google Ads היא היכולת לשלב נתונים ושירותים מממשקי API של צד שלישי.
המדריך הזה עוסק במושגים הבאים, שיכולים לעזור לכם לכתוב סקריפטים כדי להתחבר לשירותים אחרים:
- שליחת בקשות HTTP: איך משתמשים ב-
UrlFetchAppכדי לגשת לממשקי API חיצוניים. - אימות: אנחנו מתארים כמה תרחישי אימות נפוצים.
- ניתוח תשובות: איך לעבד נתוני JSON ו-XML שמוחזרים.
אנחנו כוללים גם דוגמאות לכמה ממשקי API פופולריים שממחישים את המושגים האלה.
אחזור נתונים באמצעות UrlFetchApp
UrlFetchApp מספק את הפונקציונליות העיקרית שנדרשת לאינטראקציה עם ממשקי API של צד שלישי.
בדוגמה הבאה מוצגת שליפה של נתוני מזג אוויר מ-OpenWeatherMap. בחרנו ב-OpenWeatherMap בגלל סכימת ההרשאה וה-API הפשוטים יחסית שלה.
שליחת בקשה
במסמכי התיעוד של OpenWeatherMap מפורט הפורמט לבקשת מזג האוויר הנוכחי:
http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]
כתובת ה-URL מספקת את הדוגמה הראשונה שלנו להרשאה: הפרמטר apikey נדרש, והערך ייחודי לכל משתמש. כדי לקבל את המפתח הזה צריך להירשם.
אחרי ההרשמה, אפשר לשלוח בקשה באמצעות המפתח באופן הבא:
const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());
הפעלת הקוד הזה גורמת לכתיבה של מחרוזת ארוכה של טקסט JSON בחלון הרישום ביומן בסקריפטים של Google Ads.
השלב הבא הוא להמיר את זה לפורמט שאפשר להשתמש בו בסקריפט.
נתוני JSON
ממשקי API רבים מספקים תשובות בפורמט JSON. הוא מייצג סדרה של אובייקטים ב-JavaScript, כך שאובייקטים, מערכים וסוגים בסיסיים יכולים להיות מיוצגים ומועברים כמחרוזות.
כדי להמיר מחרוזת JSON (כמו זו שמוחזרת מ-OpenWeatherMap) בחזרה לאובייקט ב-JavaScript, משתמשים ב-method המובנית JSON.parse. בהמשך לדוגמה הקודמת:
const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
// "London"
ה-method JSON.parse ממירה את המחרוזת לאובייקט, שיש לו את המאפיין name.
בקטע ניתוח תגובות מוסבר איך לעבוד עם תגובות מה-API בפורמטים שונים.
טיפול בשגיאות
כשעובדים עם ממשקי API של צד שלישי בסקריפטים, חשוב לטפל בשגיאות כי ממשקי API של צד שלישי משתנים לעיתים קרובות ויוצרים ערכי תגובה לא צפויים, לדוגמה:
- כתובת ה-URL או הפרמטרים של ה-API יכולים להשתנות בלי שתדעו.
- יכול להיות שהתוקף של מפתח ה-API (או של פרטי כניסה אחרים של משתמש) יפוג.
- הפורמט של התשובה יכול להשתנות בלי הודעה מוקדמת.
קודי מצב HTTP
בגלל האפשרות לתגובות לא צפויות, כדאי לבדוק את קוד הסטטוס של ה-HTTP. כברירת מחדל, UrlFetchApp יזרוק חריגה אם ייתקל בקוד שגיאת HTTP. כדי לשנות את ההתנהגות הזו, צריך להעביר פרמטר אופציונלי, כמו בדוגמה הבאה:
const options = {
muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
// Error encountered, send an email alert to the developer
sendFailureEmail();
}
מבנה התשובה
כשממשקי API של צד שלישי משתנים, יכול להיות שלא תהיו מודעים מיד לשינויים שעשויים להשפיע על הסקריפטים שלכם. לדוגמה, אם המאפיין name שמוחזר בדוגמה של OpenWeatherMap משתנה ל-locationName, סקריפטים שמשתמשים במאפיין הזה ייכשלו.
לכן, כדאי לבדוק אם המבנה שהוחזר הוא כמו שציפיתם, לדוגמה:
const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
console.log('Location is : ' + name);
} else {
console.log('Data not in expected format');
}
נתוני POST עם UrlFetchApp
בדוגמה הראשונית עם OpenWeatherMap, רק אחזרנו נתונים. בדרך כלל, קריאות ל-API שלא משנות את המצב בשרת המרוחק משתמשות ב-method HTTP
GET.
השיטה GET היא ברירת המחדל של UrlFetchApp. עם זאת, קריאות מסוימות ל-API, כמו קריאות לשירות ששולח הודעות SMS, ידרשו שיטות אחרות, כמו POST או PUT.
כדי להמחיש את השימוש בקריאות ל-POST באמצעות UrlFetchApp, בדוגמה הבאה מוצג שילוב עם Slack, אפליקציה לשליחת הודעות בשיתוף, כדי לשלוח הודעת Slack למשתמשים ולקבוצות ב-Slack.
הגדרת Slack
במדריך הזה אנחנו יוצאים מנקודת הנחה שכבר נרשמתם לחשבון Slack.
כמו ב-OpenWeatherMap בדוגמה הקודמת, צריך לקבל טוקן כדי לאפשר שליחת הודעות. ב-Slack יש כתובת URL ייחודית שמאפשרת לשלוח הודעות לצוות, שנקראת Incoming Webhook.
מגדירים תגובה לפעולה מאתר אחר (webhook) נכנסת: לוחצים על Add Incoming WebHooks Integration (הוספת שילוב של תגובות לפעולה מאתר אחר נכנסות) ופועלים לפי ההוראות. בסיום התהליך אמורה להתקבל כתובת URL שבה אפשר להשתמש להעברת הודעות.
שליחת בקשת POST
אחרי שמגדירים את ה-Webhook הנכנס, כדי לשלוח בקשת POST צריך להשתמש בכמה מאפיינים נוספים בפרמטר options שמועבר אל UrlFetchApp.fetch:
-
method: כמו שצוין, ברירת המחדל היאGET, אבל כאן אנחנו משנים אותה ל-POST.
payload: אלה הנתונים שיישלחו לשרת כחלק מהבקשהPOST. בדוגמה הזו, Slack מצפה לאובייקט שעבר סריאליזציה לפורמט JSON, כמו שמתואר במסמכי התיעוד של Slack. לשם כך, משתמשים ב-method [JSON.stringify][json-stringify-url] ומגדירים אתContent-Typeל-application/json.// Change the URL for the one issued to you from 'Setting up Slack'. const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC'; const slackMessage = { text: 'Hello, slack!' }; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(slackMessage) }; UrlFetchApp.fetch(SLACK_URL, options);
דוגמה מורחבת ל-Slack
בדוגמה הקודמת מוצג הקוד המינימלי שנדרש כדי לאפשר הודעות נכנסות ב-Slack. דוגמה מורחבת ממחישה את היצירה והשליחה של דוח ביצועים ברמת הקמפיין לקבוצה, וגם כמה אפשרויות עיצוב ותצוגה.

למידע נוסף על הודעות ב-Slack, קראו את המאמר עיצוב הודעות במרכז העזרה של Slack.
נתוני טופס
בדוגמה הקודמת השתמשנו במחרוזת JSON כמאפיין payload לבקשת POST.
בהתאם לפורמט של payload, UrlFetchApp משתמש בגישות שונות כדי ליצור את הבקשה של POST:
- אם
payloadהוא מחרוזת, הארגומנט של המחרוזת נשלח כגוף הבקשה. כאשר
payloadהוא אובייקט, לדוגמה מפה של ערכים:{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}צמדי המפתח/ערך מומרים לנתוני טופס:
subject=Test&to=mail@example.com&body=Hello,+World!בנוסף, הכותרת
Content-Typeשל הבקשה מוגדרת ל-application/x-www-form-urlencoded.
חלק מממשקי ה-API דורשים שימוש בנתוני טפסים כששולחים בקשות POST, לכן כדאי לזכור את ההמרה האוטומטית הזו מאובייקטים ב-JavaScript לנתוני טפסים.
אימות בסיסי של HTTP
אימות בסיסי של HTTP הוא אחת מצורות האימות הפשוטות ביותר, והוא משמש ממשקי API רבים.
האימות מתבצע על ידי צירוף שם משתמש וסיסמה מקודדים לכותרות ה-HTTP בכל בקשה.

יצירת בקשה
כדי ליצור בקשה מאומתת, צריך לבצע את השלבים הבאים:
- כדי ליצור את ביטוי הסיסמה, מחברים את שם המשתמש והסיסמה באמצעות נקודתיים, לדוגמה
username:password. - מקודדים את ביטוי הסיסמה ב-Base64, לדוגמה
username:passwordהופך ל-dXNlcm5hbWU6cGFzc3dvcmQ=. - מצרפים לבקשה כותרת
Authorization, בפורמטAuthorization: Basic <encoded passphrase>
בקטע הקוד הבא אפשר לראות איך עושים את זה בסקריפטים של Google Ads:
const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';
const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);
דוגמאות לאימות בסיסי
בקטע דוגמאות קוד יש שתי דוגמאות שממחישות איך להשתמש באימות בסיסי של HTTP:
Plivo
Plivo הוא שירות שמאפשר לשלוח ולקבל הודעות SMS באמצעות ה-API שלו. הדוגמה הזו ממחישה שליחת הודעות.
- נרשמים ל-Plivo.
- מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
- מחליפים את הערכים
PLIVO_ACCOUNT_AUTHIDו-PLIVO_ACCOUNT_AUTHTOKENבערכים ממרכז הבקרה לניהול. - מזינים את כתובת האימייל שלכם כפי שצוין בסקריפט כדי לקבל התראות על שגיאות.
- כדי להשתמש ב-Plivo, צריך לרכוש מספרים או להוסיף מספרים לחשבון לניסיון. להוסיף מספרי Sandbox שאפשר להשתמש בהם בחשבון לניסיון.
- מוסיפים את המספר שיופיע כשולח ואת המספר של הנמען.
- מעדכנים את
PLIVO_SRC_PHONE_NUMBERבסקריפט לאחד ממספרי ארגז החול שנרשמו. המספר צריך לכלול את קידומת החיוג הבינלאומית של המדינה, לדוגמה447777123456למספר בבריטניה.
Twilio
Twilio הוא שירות נוסף שמאפשר לשלוח ולקבל הודעות SMS באמצעות ה-API שלו. הדוגמה הזו ממחישה שליחת הודעות.
- נרשמים ל-Twillio.
- מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
- מחליפים את הערכים
TWILIO_ACCOUNT_SIDו-TWILIO_ACCOUNT_AUTHTOKENבערכים שמופיעים בדף החשבון במסוף. - מחליפים את
TWILIO_SRC_PHONE_NUMBERבמספר מלוח הבקרה – זה המספר שקיבל הרשאה מ-Twilio לשלוח הודעות.
OAuth 1.0
הרבה שירותים פופולריים משתמשים ב-OAuth לאימות. יש כמה סוגים וגרסאות של OAuth.
באימות בסיסי של HTTP, למשתמש יש רק שם משתמש וסיסמה אחת. לעומת זאת, OAuth מאפשר לאפליקציות של צד שלישי לקבל גישה לחשבון ולנתונים של המשתמש, באמצעות פרטי כניסה ספציפיים לאפליקציה הזו. בנוסף, היקף הגישה יהיה ספציפי לאפליקציה הזו.
למידע רקע על OAuth 1.0, אפשר לעיין במדריך הליבה של OAuth. באופן ספציפי, כדאי לעיין בסעיף 6. אימות באמצעות OAuth. ב-OAuth 1.0 תלת-רגלי מלא, התהליך הוא כזה:
- האפליקציה ("הצרכן") מקבלת אסימון בקשה.
- המשתמש מאשר את אסימון הבקשה.
- האפליקציה ממירה את אסימון הבקשה לאסימון גישה.
- בכל הבקשות הבאות למשאבים, טוקן הגישה משמש בבקשה חתומה.
כדי ששירותים של צד שלישי ישתמשו ב-OAuth 1.0 בלי אינטראקציה של המשתמש (לדוגמה, כמו שנדרש בסקריפטים של Google Ads), אי אפשר לבצע את שלבים 1, 2 ו-3. לכן, חלק מהשירותים מנפיקים טוקן גישה ממסוף ההגדרות שלהם, וכך האפליקציה יכולה לעבור ישירות לשלב 4. התהליך הזה נקרא OAuth 1.0 עם רגל אחת.

OAuth 1.0 בסקריפטים של Google Ads
בסקריפטים של Google Ads, כל סקריפט בדרך כלל מפורש כאפליקציה. בדרך כלל, צריך לבצע את הפעולות הבאות דרך המסוף או דף הגדרות הניהול של השירות:
- מגדירים את האפליקציה כך שתייצג את הסקריפט.
- מציינים אילו הרשאות ניתנות לסקריפט.
- משיגים את טוקן הצרכן, סוד הצרכן, טוקן הגישה וסוד הגישה לשימוש ב-OAuth עם רגל אחת.
OAuth 2.0
OAuth 2.0 משמש בממשקי API פופולריים כדי לספק גישה לנתוני משתמשים. הבעלים של חשבון בשירות של צד שלישי נותן הרשאה לאפליקציות ספציפיות כדי לאפשר להן לגשת לנתוני המשתמשים. היתרונות הם שהבעלים:
- לא צריך לשתף את פרטי הכניסה לחשבון עם האפליקציה.
- יכולים לקבוע לאילו אפליקציות תהיה גישה לנתונים, ומה תהיה רמת הגישה. (לדוגמה, יכול להיות שהגישה שניתנה היא לקריאה בלבד, או רק לקבוצת משנה של הנתונים).
כדי להשתמש בשירותים שמופעל בהם OAuth 2.0 בסקריפטים של Google Ads, צריך לבצע כמה שלבים:
- מחוץ לתסריט שלך
נותנים לסקריפטים של Google Ads הרשאה לגשת לנתוני המשתמשים דרך ה-API של הצד השלישי. ברוב המקרים, זה כולל הגדרת אפליקציה במסוף של שירות הצד השלישי. האפליקציה הזו מייצגת את הסקריפט שלכם.
אתם מציינים אילו הרשאות גישה לתת לאפליקציה של הסקריפטים של Google Ads, ובדרך כלל יוקצה לה מזהה לקוח. כך אתם יכולים להשתמש ב-OAuth 2.0 כדי לקבוע לאילו אפליקציות תהיה גישה לנתונים שלכם בשירות של הצד השלישי, וגם אילו חלקים מהנתונים האלה הן יוכלו לראות או לשנות.
- בסקריפט שלכם
אישור מול השרת המרוחק. בהתאם לסוג ה-grant שהשרת אישר, צריך לבצע קבוצה שונה של שלבים, שנקראת תהליך, אבל כולם יגרמו בסופו של דבר להנפקת אסימון גישה שישמש לאותו סשן בכל הבקשות הבאות.
שליחת בקשות API. מעבירים את טוקן הגישה עם כל בקשה.
תהליכי הרשאה
כל סוג grant ותהליך תואם מתאימים לתרחישי שימוש שונים. לדוגמה, תהליך שונה משמש כשמשתמש משתתף בסשן אינטראקטיבי, בניגוד לתרחיש שבו אפליקציה נדרשת לפעול ברקע ללא נוכחות של משתמש.
ספקי ה-API יחליטו אילו סוגי grant הם מקבלים, וזה יקבע איך המשתמש ימשיך בשילוב ה-API שלהם.
הטמעה
בכל תהליכי ה-OAuth השונים, המטרה היא לקבל טוקן גישה שבו אפשר להשתמש בשאר הסשן כדי לאמת בקשות.
ספרייה לדוגמה, שממחישה איך לבצע אימות לכל סוג תהליך. כל אחת מהשיטות האלה מחזירה אובייקט שמקבל ומאחסן את טוקן הגישה, ומאפשר בקשות מאומתות.
דפוס השימוש הכללי הוא:
// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);
הענקת פרטי כניסה של לקוח
[הענקת פרטי כניסה של לקוח][client-credentials-rfc] היא אחת מהצורות הפשוטות יותר של תהליך OAuth2, שבה האפליקציה מחליפה מזהה וסוד, הייחודיים לאפליקציה, בתמורה להנפקת אסימון גישה מוגבל בזמן.

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response
הענקת טוקן רענון
הענקת טוקן רענון דומה להענקת פרטי כניסה של לקוח, בכך שבקשה לשרת תחזיר טוקן גישה שאפשר להשתמש בו בסשן.

קבלת טוקן רענון
ההבדל בין הענקת טוקן רענון לבין הענקת פרטי כניסה של לקוח הוא שהפרטים שנדרשים להענקת פרטי כניסה של לקוח מגיעים מהגדרות האפליקציה (לדוגמה, בלוח הבקרה של השירות), ואילו טוקן הרענון מוענק כחלק מתהליך מורכב יותר, כמו [הענקת קוד הרשאה][authorization-code-rfc], שדורש אינטראקציה עם המשתמש:

- שימוש ב-OAuth Playground כדי לקבל טוקן רענון
ב-OAuth2 playground יש ממשק משתמש שמאפשר למשתמש לעבור את תהליך הענקת קוד ההרשאה כדי לקבל טוקן רענון.
כפתור ההגדרות בפינה השמאלית העליונה מאפשר להגדיר את כל הפרמטרים לשימוש בתהליך OAuth, כולל:
- נקודת קצה להרשאה: משמשת כתחילת התהליך להרשאה.
- נקודת קצה של טוקן: משמשת עם טוקן הרענון כדי לקבל טוקן גישה.
מזהה לקוח וסוד: פרטי הכניסה לאפליקציה.

שימוש בטוקן רענון
אחרי שההרשאה הראשונית בוצעה, השירותים יכולים להנפיק טוקן רענון, שאפשר להשתמש בו באופן דומה לתהליך של פרטי הכניסה של הלקוח:
const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response
דוגמה ל-Search Ads 360
Search Ads 360 הוא דוגמה ל-API שאפשר להשתמש בו עם טוקן רענון. בדוגמה הזו, סקריפט יוצר ומחזיר דוח. במאמרי העזרה של Search Ads 360 API מפורטות פעולות נוספות שאפשר לבצע.
יצירת הסקריפט
- יוצרים פרויקט חדש במסוף Google Cloud ומקבלים מזהה לקוח, סוד לקוח וטוקן רענון. כדי לעשות את זה, פועלים לפי ההוראות במדריך של Search Ads 360 ומפעילים את Search Ads 360 API.
- מדביקים את [הסקריפט לדוגמה][search-ads-360-example] בסקריפט חדש ב-Google Ads.
- מדביקים את [ספריית OAuth2 לדוגמה][oauth20-library-example] מתחת לרשימת הקוד.
- משנים את הסקריפט כך שיכיל את הערכים הנכונים של מזהה הלקוח, סוד הלקוח וטוקן הרענון.
דוגמה ל-Apps Script Execution API
בדוגמה הזו מוסבר איך להריץ פונקציה ב-Apps Script באמצעות Apps Script Execution API. כך אפשר להפעיל את Apps Script מסקריפטים של Google Ads.
יצירת סקריפט ב-Apps Script
יוצרים סקריפט חדש. בדוגמה הבאה מוצגת רשימה של 10 קבצים מ-Drive:
function listFiles() {
const limit = 10;
const files = [];
const fileIterator = DriveApp.getFiles();
while (fileIterator.hasNext() && limit) {
files.push(fileIterator.next().getName());
limit--;
}
return files;
}
הגדרת Apps Script להפעלה
- שומרים את הסקריפט.
- לוחצים על Resources > Cloud Platform project.
- לוחצים על שם הפרויקט כדי לעבור למסוף Google Cloud.
- עוברים אל APIs & Services.
- מפעילים את ממשקי ה-API המתאימים, במקרה הזה Drive API ו-Apps Script Execution API.
- יוצרים פרטי כניסה ל-OAuth מהפריט Credentials בתפריט.
- חוזרים לסקריפט ומפרסמים אותו להפעלה דרך Publish > Deploy as API Executable.
יצירת הסקריפט של Google Ads
- מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
- בנוסף, מדביקים את [ספריית OAuth2 לדוגמה][oauth20-library-example] מתחת לרשימת הקוד.
- משנים את הסקריפט כך שיכיל את הערכים הנכונים של מזהה הלקוח, סוד הלקוח וטוקן הרענון.
חשבונות שירות
חלופה לסוגי grant היא הקונספט של חשבונות שירות.
חשבונות שירות שונים מסוגי grant בכך שהם לא משמשים לגישה לנתוני משתמשים: אחרי האימות, הבקשות נשלחות על ידי חשבון השירות בשם האפליקציה, ולא בתור המשתמש שבבעלותו הפרויקט. לדוגמה, אם חשבון השירות משתמש ב-Drive API כדי ליצור קובץ, הקובץ יהיה שייך לחשבון השירות, ולבעלים של הפרויקט לא תהיה גישה אליו כברירת מחדל.
דוגמה ל-Google Natural Language API
[Natural Language API][natural-language-api-docs] מספק [ניתוח סנטימנטים][sentiment-analysis-api-docs] ו[ניתוח ישויות][entity-analysis-api-docs] לטקסט.
בדוגמה הזו מוסבר איך לחשב את [הסנטימנט][sentiment-api-docs] של טקסט המודעה, כולל הכותרת או התיאור. כך אפשר למדוד עד כמה המסר חיובי ומה העוצמה שלו: מה עדיף, אנחנו מוכרים עוגות או אנחנו מוכרים את העוגות הכי טובות בלונדון? כדאי לקנות עוד היום!?
הגדרת הסקריפט
- יוצרים פרויקט חדש במסוף Google Cloud.
- מפעילים את [Natural Language API][natural-language-api].
- מפעילים את החיוב בפרויקט.
- [יצירת חשבון שירות][create-service-account]. מורידים את קובץ ה-JSON של פרטי הכניסה.
- מדביקים את [הסקריפט לדוגמה][natural-language-example] בסקריפט חדש ב-Google Ads.
- בנוסף, מדביקים את [ספריית OAuth2 לדוגמה][oauth20-library-example] מתחת לרשימת הקוד.
- מחליפים את הערכים הרלוונטיים:
-
serviceAccount: כתובת האימייל של חשבון השירות, לדוגמהxxxxx@yyyy.iam.gserviceaccount.com. -
key: המפתח מקובץ ה-JSON שהורדתם כשיצרתם את חשבון השירות. מתחיל ב------BEGIN PRIVATE KEY...ומסתיים ב-...END PRIVATE KEY-----\n.
-
תגובות מה-API
ממשקי API יכולים להחזיר נתונים במגוון פורמטים. הבולטים שבהם הם XML ו-JSON.
JSON
בדרך כלל קל יותר לעבוד עם JSON מאשר עם XML כפורמט תגובה. עם זאת, עדיין יכולות להיות בעיות.
אימות תשובות
אחרי שמקבלים תגובה תקינה מהקריאה ל-API, השלב הבא הוא בדרך כלל להשתמש ב-JSON.parse כדי להמיר את מחרוזת ה-JSON לאובייקט ב-JavaScript.
בשלב הזה, כדאי לטפל במקרה שבו הניתוח נכשל:
const json = response.getContentText();
try {
const data = JSON.parse(json);
return data;
} catch(e) {
// Parsing of JSON failed - handle error.
}
בנוסף, אם ה-API לא בשליטתכם, יכול להיות שמבנה התגובה ישתנה, ושהמאפיינים לא יהיו קיימים יותר:
// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;
// Better approach
if (data && data.queryResponse) {
const answer = data.queryResponse;
} else {
// Format of API response has changed - alert developer or handle accordingly
}
XML
השירות XmlService מאפשר לסקריפטים לנתח ולחלץ נתונים מגופי תגובה ב-XML.
אימות
XML הוא עדיין פורמט פופולרי ליצירת ממשקי API. אפשר לנתח תגובה מקריאה ל-API באמצעות השיטה XmlService parse:
const responseText = response.getContentText();
try {
const document = XmlService.parse(responseText);
} catch(e) {
// Error in XML representation - handle accordingly.
}
אמנם XmlService.parse מזהה שגיאות ב-XML ומחזיר חריגות בהתאם, אבל הוא לא מספק את היכולת לאמת את ה-XML מול סכימה.
רכיב בסיס
אם הניתוח של מסמך ה-XML הצליח, רכיב הבסיס מתקבל באמצעות השיטה getRootElement():
const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();
מרחבי שמות
בדוגמה הבאה, משתמשים ב-Sportradar API כדי לקבל תוצאות של משחקי כדורגל נבחרים. תגובת ה-XML היא בפורמט הבא:
<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
<schedule>
...
</schedule>
</schedule_schedules>
שימו לב איך מרחב השמות מצוין ברכיב הבסיס. לכן צריך:
- מחלצים את מאפיין מרחב השמות מהמסמך.
- צריך להשתמש במרחב השמות הזה כשעוברים בין אלמנטים משניים וניגשים אליהם.
בדוגמה הבאה אפשר לראות איך לגשת לרכיב <schedule> ולחפש את רכיבי המשנה <sport_event> שלו בקטע המסמך הקודם:
const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);
קבלת ערכים
לפי הדוגמה של לוח הזמנים של משחקי הכדורגל:
<sport_event_status status="..." ... />
אפשר לאחזר מאפיינים, לדוגמה:
const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();
אפשר לקרוא טקסט שכלול ברכיב באמצעות getText(), אבל אם יש כמה רכיבי צאצא של טקסט ברכיב, הם ישורשרו. אם סביר להניח שיהיו כמה צאצאי טקסט, כדאי להשתמש ב-getChildren() ולעבור על כל צאצא.
דוגמה ל-Sportradar
בדוגמה המלאה הזו של Sportradar מוצג אחזור של פרטים על משחקי כדורגל, ובמיוחד משחקים של הפרמייר ליג האנגלית. Soccer API הוא אחד ממגוון רחב של פידים של ספורט ש-Sportradar מציעה.
הגדרת חשבון Sportradar
- עוברים אל אתר המפתחים של Sportradar.
- נרשמים לחשבון לתקופת ניסיון.
- אחרי שנרשמים, נכנסים לחשבון.
- אחרי שמתחברים, עוברים אל החשבון שלי.
ב-Sportradar, ענפי ספורט שונים מופרדים לממשקי API שונים. לדוגמה, יכול להיות שתרכשו גישה ל-Soccer API אבל לא ל-Tennis API. לכל אפליקציה שאתם יוצרים יכולים להיות ענפי ספורט שונים שמשויכים אליה, ומפתחות שונים.
- בקטע Applications (אפליקציות), לוחצים על Create a new Application (יצירת אפליקציה חדשה). נותנים לאפליקציה שם ותיאור, ומתעלמים מהשדה של האתר.
- בוחרים רק באפשרות הנפקת מפתח חדש ל-Soccer Trial Europe v2.
- לוחצים על Register Application (רישום האפליקציה).
אם הפעולה תצליח, יופיע דף עם מפתח ה-API החדש.
- מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
- מחליפים את מפתח ה-API ברשימה במפתח החדש שהונפק, ועורכים את השדה של כתובת האימייל.
פתרון בעיות
כשעובדים עם ממשקי API של צד שלישי, יכולות להיות כמה סיבות לשגיאות, למשל:
- לקוחות ששולחים בקשות לשרת בפורמט שלא צפוי על ידי ה-API.
- לקוחות שמצפים לפורמט תגובה שונה מזה שנתקלו בו.
- לקוחות שמשתמשים בטוקנים או במפתחות לא תקינים, או בערכים שנותרו כפלייסהולדרים.
- לקוחות שמגיעים למגבלות השימוש.
- לקוחות שמספקים פרמטרים לא תקינים.
בכל המקרים האלה, ובמקרים אחרים, הצעד הראשון לזיהוי הגורם לבעיה הוא לבדוק את פרטי התגובה שגורמת לשגיאה.
ניתוח התשובות
כברירת מחדל, כל תגובה שמחזירה שגיאה (קוד סטטוס של 400 ומעלה) תיזרק על ידי מנוע הסקריפטים של Google Ads.
כדי למנוע את ההתנהגות הזו, וכדי לאפשר בדיקה של השגיאה והודעת השגיאה, מגדירים את המאפיין muteHttpExceptions של הפרמטרים האופציונליים לערך UrlFetchApp.fetch. לדוגמה:
const params = {
muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
// ... inspect error details...
}
קודי סטטוס נפוצים
הערך
200 OKמציין הצלחה. אם התשובה לא מכילה את הנתונים שציפיתם לקבל, יכול להיות ש:- בחלק מממשקי ה-API אפשר לציין באילו שדות, פורמט תגובה או שניהם להשתמש. פרטים נוספים זמינים במאמרי העזרה של ה-API.
- ל-API יכולים להיות כמה משאבים שאפשר לקרוא להם. כדאי לעיין במסמכי התיעוד כדי לבדוק אם יש משאב אחר שמתאים יותר לשימוש, ושיחזיר את הנתונים שאתם צריכים.
- יכול להיות שה-API השתנה מאז שהקוד נכתב. כדי לקבל הבהרות, אפשר לעיין במסמכי התיעוד או לפנות למפתח.
השגיאה
400 Bad Requestבדרך כלל מציינת שיש בעיה בפורמט או במבנה של הבקשה שנשלחה לשרת. בודקים את הבקשה ומשווים אותה למפרט ה-API כדי לוודא שהיא תואמת לציפיות. בקטע בדיקת בקשות מוסבר איך לבדוק את הבקשות.השגיאה
401 Unauthorizedבדרך כלל מציינת שה-API נקרא בלי לספק הרשאה או בלי לבצע אותה בהצלחה.- אם ה-API משתמש בהרשאה בסיסית, צריך לוודא שהכותרת
Authorizationנוצרת ומסופקת בבקשה. - אם ה-API משתמש ב-OAuth 2.0, ודאו שקיבלתם את טוקן הגישה ושהוא מסופק כטוקן למוכ"ז.
- בכל וריאציה אחרת של הרשאה, ודאו שאתם מספקים את פרטי הכניסה הנדרשים לבקשה.
- אם ה-API משתמש בהרשאה בסיסית, צריך לוודא שהכותרת
השגיאה
403 Forbiddenמציינת שלמשתמש אין הרשאה למשאב המבוקש.- מוודאים שלמשתמש יש את ההרשאות הנדרשות, למשל, נותנים למשתמש גישה לקובץ בבקשה שמבוססת על קובץ.
המשמעות של
404 Not Foundהיא שהמשאב המבוקש לא קיים.- מוודאים שכתובת ה-URL שמשמשת לנקודת הקצה ל-API נכונה.
- אם מאחזרים משאב, צריך לוודא שהמשאב שאליו מפנים קיים (לדוגמה, אם הקובץ קיים ב-API שמבוסס על קבצים).
בדיקת בקשות
בדיקת הבקשות שימושית כשהתגובות מה-API מציינות שהבקשה לא תקינה, למשל קוד סטטוס 400. כדי לבדוק בקשות, ל-UrlFetchApp יש method נלווית ל-method fetch(), שנקראת getRequest(url,
params).
במקום לשלוח בקשה לשרת, ה-method הזו יוצרת את הבקשה שהייתה נשלחת ומחזירה אותה. כך המשתמש יכול לבדוק את רכיבי הבקשה כדי לוודא שהיא נראית תקינה.
לדוגמה, אם נתוני הטופס בבקשה מורכבים ממחרוזות רבות שמשורשרות יחד, יכול להיות שהשגיאה נמצאת בפונקציה שיצרתם כדי ליצור את נתוני הטופס האלה. במילים פשוטות:
const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...
מאפשרת לבדוק את הרכיבים של הבקשה.
רישום בקשות ותשובות ביומן
כדי לעזור בכל התהליך של בדיקת הבקשות והתגובות ל-API של צד שלישי, אפשר להשתמש בפונקציית העזר הבאה כתחליף ל-UrlFetchApp.fetch(), כדי לתעד גם בקשות וגם תגובות.
מחליפים את כל המופעים של
UrlFetchApp.fetch()בקוד ב-logUrlFetch().מוסיפים את הפונקציה הבאה בסוף הסקריפט.
function logUrlFetch(url, opt_params) { const params = opt_params || {}; params.muteHttpExceptions = true; const request = UrlFetchApp.getRequest(url, params); console.log('Request: >>> ' + JSON.stringify(request)); const response = UrlFetchApp.fetch(url, params); console.log('Response Code: <<< ' + response.getResponseCode()); console.log('Response text: <<< ' + response.getContentText()); if (response.getResponseCode() >= 400) { throw Error('Error in response: ' + response); } return response; }
כשמריצים את הסקריפט, הפרטים של כל הבקשות והתגובות מתועדים במסוף, וכך קל יותר לנפות באגים.
[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities