ממשקי API של צד שלישי

תכונה מתקדמת של סקריפטים של Google Ads היא היכולת לשלב אותם עם נתונים ושירותים מממשקי API של צד שלישי.

במדריך הזה מוסבר על המושגים הבאים שיכולים לעזור לכם לכתוב סקריפטים כדי להתחבר לשירותים אחרים:

  • יצירת בקשות HTTP: איך משתמשים ב-UrlFetchApp כדי לגשת לממשקי API חיצוניים.
  • אימות: נסביר על כמה תרחישי אימות נפוצים.
  • ניתוח תשובות: איך לעבד נתוני JSON ו-XML שהוחזרו.

אחזור נתונים באמצעות 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, צריך להשתמש בשיטה JSON.parse המובנית. נמשיך מהדוגמה שלמעלה:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

השיטה 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 ייחודית שמאפשרת לשלוח הודעות לצוות. הכתובת הזו נקראת Inbound Webhook.

כדי להגדיר תגובה לפעולה מאתר אחר (webhook), לוחצים על Add Inbound WebHooks Integration (הוספת שילוב של WebHooks) ופועלים לפי ההוראות. התהליך צריך לכלול כתובת URL לצורך העברת ההודעות.

שליחה של בקשת POST

אחרי שמגדירים תגובה לפעולה מאתר אחר (webhook) כדי לשלוח בקשת POST, צריך רק להשתמש בכמה מאפיינים נוספים בפרמטר options שמועבר אל UrlFetchApp.fetch:

  • method: כפי שצוין, ברירת המחדל היא GET, אבל כאן אנחנו מחליפים אותה ומגדירים את הערך POST.

  • payload: אלה הנתונים שיישלחו לשרת כחלק מהבקשה POST. בדוגמה הזו, Slack מצפה שאובייקט עם סדרה יהיה בפורמט JSON כמו שמתואר במסמכי התיעוד ב-Slack. לשם כך משתמשים ב-method JSON.stringify, והערך 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);

דוגמה ל-Extended 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 בכל בקשה.

אימות בסיסי ב-HTTP

יצירת בקשה

כדי ליצור בקשה מאומתת:

  1. כדי ליצור את ביטוי הסיסמה, צריך לחבר את שם המשתמש והסיסמה באמצעות נקודתיים. לדוגמה: username:password.
  2. Base64 מקודד את ביטוי הסיסמה. לדוגמה, username:password הופך ל-dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. צריך לצרף לבקשה כותרת 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);

Plivo

Plivo הוא שירות שעוזר לשלוח ולקבל הודעות SMS דרך ה-API. בדוגמה הזו אפשר לראות איך שולחים הודעות.

  1. נרשמים ב-Plivo.
  2. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  3. מחליפים את הערכים PLIVO_ACCOUNT_AUTHID ו-PLIVO_ACCOUNT_AUTHTOKEN בערכים ממרכז הבקרה לניהול.
  4. עליכם להזין את כתובת האימייל כפי שהיא מופיעה בסקריפט, כדי לדווח על שגיאות.
  5. כדי להשתמש ב-Plivo צריך לרכוש מספרים או להוסיף מספרים לחשבון לניסיון. מוסיפים מספרי Sandbox שבהם אפשר להשתמש עם החשבון לניסיון.
  6. מוסיפים גם את המספר שיופיע כשולח וגם את מספר הנמען.
  7. מעדכנים בסקריפט את PLIVO_SRC_PHONE_NUMBER לאחד ממספרי ה-Sandbox שרשומים כרגע. צריך לכלול את קוד המדינה הבינלאומי, לדוגמה 447777123456 למספר בבריטניה.

Twilio

Twilio הוא שירות נוסף שעוזר לשלוח ולקבל הודעות SMS דרך ה-API. בדוגמה הזו אפשר לראות איך שולחים הודעות.

  1. נרשמים ב-TWillio.
  2. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  3. מחליפים את הערכים TWILIO_ACCOUNT_SID ו-TWILIO_ACCOUNT_AUTHTOKEN בערכים שמוצגים בדף של מסוף החשבון.
  4. מחליפים את TWILIO_SRC_PHONE_NUMBER במספר מלוח הבקרה – זהו המספר המורשה על ידי Twilio לשלוח הודעות.

OAuth 1.0

שירותים פופולריים רבים משתמשים ב-OAuth לצורך אימות. ל-OAuth יש כמה טעמים וגרסאות.

באימות בסיסי של HTTP, למשתמש יש רק שם משתמש אחד וסיסמה, ואילו OAuth מאפשר לאפליקציות צד שלישי לקבל גישה לחשבון ולנתונים של המשתמש, באמצעות פרטי כניסה ספציפיים לאותה אפליקציית צד שלישי. בנוסף, היקף הגישה יהיה גם הוא ספציפי לאותה אפליקציה.

לקבלת רקע על OAuth 1.0, ניתן לעיין במדריך הליבה של OAuth. במיוחד, ראה 6. אימות באמצעות OAuth. בגרסה מלאה של OAuth 1.0 עם שלוש רגליים, התהליך הוא:

  1. האפליקציה ("צרכן") מקבלת אסימון בקשה.
  2. המשתמש מאשר את אסימון הבקשה.
  3. האפליקציה ממירה את אסימון הבקשה באסימון גישה.
  4. בכל בקשות המשאבים הבאות, המערכת משתמשת באסימון הגישה בבקשה חתומה.

לא ניתן לבצע את השלבים 1,2 ו-3 כדי ששירותי צד שלישי ישתמשו ב-OAuth 1.0 ללא אינטראקציה של משתמש (לדוגמה, כפי שנדרש על ידי סקריפטים של Google Ads). לכן, שירותים מסוימים מנפיקים אסימון גישה ממסוף ההגדרות שלהם, וכך מאפשרים לאפליקציה לעבור ישירות לשלב 4. השיטה הזו נקראת OAuth 1.0 חד-רגלי.

OAuth1

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.

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

בסקריפט שלך

הרשאה באמצעות השרת המרוחק. בהתאם לסוג ההרשאה שהשרת אישר, יש לבצע קבוצה אחרת של שלבים (flow), אבל כולן יובילו ליצירת אסימון גישה שישמש לסשן הזה בכל הבקשות הבאות.

שולחים בקשות API. מעבירים את אסימון הגישה בכל בקשה.

תהליכי ההרשאה

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

ספקי ה-API מחליטים אילו סוגי הרשאות הם יקבלו, והם ינחו את המשך השילוב של ה-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);

הענקת פרטי כניסה של לקוח

ההענקת פרטי הכניסה של הלקוח היא אחת מהצורות הפשוטות יותר בתהליך 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

הענקת אסימון רענון

המענק של אסימון הרענון דומה לאישור של פרטי הכניסה של הלקוח, מכיוון שבקשה פשוטה לשרת תחזיר אסימון גישה שאפשר להשתמש בו בסשן.

רענון האסימון

קבלת אסימון רענון

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

קוד הרשאה

שימוש ב-OAuth Playground לקבלת אסימון רענון

במגרש המשחקים של OAuth2 יש ממשק משתמש שמאפשר למשתמש לעבור על קוד ההרשאה שניתנו כדי לקבל אסימון רענון.

לחצן ההגדרות בפינה השמאלית העליונה מאפשר להגדיר את כל הפרמטרים שיהיו בשימוש בתהליך OAuth, כולל:

  • נקודת קצה להרשאה: משמשת כתחילת התהליך להרשאה.
  • נקודת הקצה של האסימון: משתמשים בה יחד עם אסימון הרענון כדי לקבל אסימון גישה.
  • client ID ו-Secret: פרטי הכניסה לאפליקציה.

מגרש משחקים ל-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.

יצירת הסקריפט
  1. יוצרים פרויקט חדש ב-API Console ומקבלים מזהה לקוח, סוד לקוח ואסימון רענון לפי השלבים שמפורטים במדריך של DoubleClick, תוך הקפדה על הפעלת DoubleClick Search API.
  2. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  3. מדביקים את ספריית OAuth2 לדוגמה מתחת לרישום הקוד.
  4. מתקנים את הסקריפט כך שיכלול את הערכים הנכונים של מזהה לקוח, סוד לקוח ואסימון רענון.

דוגמה ל-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 להפעלה
  1. שומרים את הסקריפט.
  2. לוחצים על Resources > Cloud Platform project.
  3. לוחצים על שם הפרויקט כדי לעבור אל מסוף ה-API.
  4. עוברים אל APIs & Services (ממשקי API ושירותים).
  5. מפעילים את ממשקי ה-API המתאימים, במקרה הזה, Drive API ו-Apps Script Execution API.
  6. יוצרים פרטי כניסה ל-OAuth מהפריט Credentials בתפריט.
  7. חוזרים לסקריפט, מפרסמים את הסקריפט להפעלה דרך פרסום > פריסה כניתן להפעלה של API.
יצירת הסקריפט של Google Ads
  1. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  2. בנוסף, מדביקים את ספריית OAuth2 לדוגמה מתחת לרישום הקוד.
  3. מתקנים את הסקריפט כך שיכלול את הערכים הנכונים של מזהה לקוח, סוד לקוח ואסימון רענון.

חשבונות השירות

האפשרות חשבונות שירות היא כחלופה לסוגי ההרשאות שלמעלה.

חשבונות שירות שונים מאלה שצוינו כי הם לא משמשים לגישה לנתוני משתמשים: לאחר האימות, בקשות מחשבון השירות נשלחות בשם האפליקציה, ולא בתור המשתמש שעשוי להיות הבעלים של הפרויקט. לדוגמה, אם חשבון השירות משתמש ב-Drive API כדי ליצור קובץ, הוא יהיה שייך לחשבון השירות וכברירת מחדל הוא לא יהיה נגיש לבעלים של הפרויקט.

דוגמה ל-API של Google בשפה טבעית

ה-API של שפה טבעית מספק ניתוח סנטימנטים וניתוח ישויות לטקסט.

בדוגמה הזו אפשר לראות איך לחשב את הדעה של הטקסט של המודעה, כולל הכותרת או התיאור. כך אפשר לבדוק עד כמה המסר הוא חיובי ומה גודל המסר: מה טוב יותר, אנחנו מוכרים עוגות או אנחנו מוכרים את העוגות הכי טובות בתל אביב. קנו היום!?

הגדרת הסקריפט
  1. יצירת פרויקט חדש ב-API Console
  2. מפעילים את Natural Language API
  3. מפעילים את החיוב בפרויקט.
  4. יוצרים חשבון שירות. מורידים את קובץ ה-JSON של פרטי הכניסה.
  5. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  6. בנוסף, מדביקים את ספריית OAuth2 לדוגמה מתחת לרישום הקוד.
  7. מחליפים את הערכים הנחוצים:
    • 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

אימות

XML הוא עדיין פורמט פופולרי לבניית ממשקי API. אפשר לנתח את התשובה מקריאה ל-API באמצעות method 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 xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

שימו לב איך מרחב השמות מצוין ברכיב הבסיס. לכן צריך:

  • מחלצים את מאפיין מרחב השמות מהמסמך.
  • יש להשתמש במרחב השמות הזה כשעוברים בין רכיבי צאצא וניגשים אליהם.

הדוגמה הבאה מראה איך לגשת לרכיב <matches> בקטע הקוד של המסמך שלמעלה:

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

קבלת ערכים

על סמך הדוגמה מלוח הזמנים של משחקי הכדורגל:

<match status="..." category="..." ... >
  ...
</match>

ניתן לאחזר מאפיינים, לדוגמה:

const status = matchElement.getAttribute('status').getValue();

אפשר לקרוא טקסט שנכלל בתוך רכיב באמצעות getText(), אבל אם יש רכיבי צאצא מרובים של טקסט, יתבצע שרשור שלהם. כדאי להשתמש ב-getChildren() ולחזור על כל ילד או ילדה במקרים שבהם יש סיכוי גבוה שכמה ילדים ישתמשו בטקסט.

דוגמה ל-Sportradar

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

הגדרת חשבון ב-Sportradar
  1. נכנסים לאתר למפתחים של Sportradar
  2. נרשמים לחשבון ניסיון.
  3. לאחר ההרשמה, צריך להיכנס לחשבון.
  4. לאחר ההתחברות, מנווטים אל MyAccount.

Sportradar מפריד בין ענפי ספורט שונים לממשקי API שונים. לדוגמה, יכול להיות שתרכשו גישה ל-NFL API, אבל לא ל-Tennis API. לכל אפליקציה שאתם יוצרים יכולים להיות משויכים סוגי ספורט שונים ומפתחות שונים.

  1. בקטע 'אפליקציות', לוחצים על יצירת אפליקציה חדשה. נותנים לאפליקציה שם ותיאור ומתעלמים מהשדה של האתר.
  2. בוחרים רק באפשרות הנפקת מפתח חדש לגרסת הניסיון של הכדורגל האירופית v2.
  3. לוחצים על רישום אפליקציה.

לאחר הפעולה, ייווצר דף עם מפתח ה-API החדש.

  1. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  2. מחליפים את מפתח ה-API שמופיע בדף העסקי במפתח שמופיע למעלה, ועורכים את השדה של כתובת האימייל.

פתרון בעיות

בעבודה עם ממשקי API של צד שלישי, שגיאות יכולות להתרחש מכמה סיבות. לדוגמה:

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

בכל המקרים האלה ובאחרים, כדי לזהות את הגורם לבעיה, כדאי לבדוק את פרטי התגובה שגורמת לשגיאה.

ניתוח התשובות

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

  • 403 Forbidden מציין שלמשתמש אין הרשאה למשאב המבוקש.

    • לוודא שהמשתמש קיבל את ההרשאות הנדרשות, לדוגמה, מתן גישה לקובץ באמצעות בקשה מבוססת-קובץ.

  • המשמעות של 404 Not Found היא שהמשאב המבוקש לא קיים.

    • חשוב לוודא שכתובת ה-URL שמשמשת כנקודת הקצה של ה-API נכונה.
    • אם מאחזרים משאב, כדאי לוודא שהמשאב שאליו מתבצעת ההפניה קיים (לדוגמה, אם הקובץ קיים ב-API מבוסס קבצים).

בדיקת בקשות

כדאי לבדוק בקשות כשהתגובות ל-API מראות שהפורמט של הבקשה שגוי, למשל קוד סטטוס 400. כדי לעזור בבדיקת בקשות, UrlFetchApp כוללת שיטה נלווית לשיטה fetch(), שנקראת getRequest()

במקום לשלוח בקשה לשרת, השיטה הזו יוצרת את הבקשה שהית נשלחת ואז מחזירה אותה. כך המשתמשים יכולים לבדוק רכיבים בבקשה כדי לוודא שהבקשה נראית נכונה.

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

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

תאפשר לך לבדוק את רכיבי הבקשה.

רישום של בקשות ותגובות

כדי לעזור לכם בכל התהליך של בדיקת הבקשות והתשובות ל-API של צד שלישי, תוכלו להשתמש בפונקציית המסייע הבאה כתחליף ל-UrlFetchApp.fetch() לתעד גם את הבקשות וגם את התשובות.

  1. מחליפים את כל המופעים של UrlFetchApp.fetch() בקוד ב-logUrlFetch().

  2. מוסיפים את הפונקציה הבאה לסוף הסקריפט.

    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;
}

כשמריצים את הסקריפט, הפרטים של כל הבקשות והתגובות נרשמים במסוף כך שניתן לנפות באגים בקלות.