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

תכונה חשובה של סקריפטים ל-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, משתמשים בשיטה המובנית 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 שלא משנות את המצב בשרת המרוחק משתמשות בשיטה 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 (הוספת שילוב של תגובה לפעולה מאתר אחר (webhook) על נתונים נכנסים) ופועלים לפי ההוראות. התהליך צריך להפיק כתובת URL לשימוש בהודעות.

שליחת בקשת POST

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

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

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

אימות 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);

דוגמאות לאימות בסיסי

בקטע דוגמאות קוד יש שתי דוגמאות שממחישות את השימוש באימות HTTP בסיסי:

Plivo

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

  1. נרשמים ל-Plivo.
  2. מדביקים את הסקריפט לדוגמה בסקריפט חדש ב-Google Ads.
  3. מחליפים את הערכים PLIVO_ACCOUNT_AUTHID ו-PLIVO_ACCOUNT_AUTHTOKEN בערכים ממרכז השליטה לניהול.
  4. מזינים את כתובת האימייל שלכם כפי שמצוין בסקריפט לקבלת התראות על שגיאות.
  5. כדי להשתמש ב-Plivo, צריך לרכוש מספרים או להוסיף מספרים לחשבון הניסיון. מוסיפים מספרי ארגז חול שאפשר להשתמש בהם בחשבון הניסיון.
  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 Core. כדאי לקרוא באופן ספציפי את הקטע 6. אימות באמצעות OAuth. ב-OAuth 1.0 מלא עם שלושה רגליים, התהליך הוא כזה:

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

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

בסקריפט

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

שליחת בקשות 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);

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

[הענקת הרשאה לפרטי לקוח][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, כולל:

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

  • מזהה לקוח וסוד לקוח: פרטי הכניסה לאפליקציה.

    OAuth Playground

השימוש בטוקן רענון

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

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

דוגמה ל-Search Ads 360

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

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

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

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

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

דוגמה ל-Google natural language API

‫[Natural Language API][natural-language-api-docs] מספק [ניתוח סנטימנט][sentiment-analysis-api-docs] ו[ניתוח ישויות][entity-analysis-api-docs] לטקסט.

בדוגמה הזו מוסבר איך לחשב את [הסנטימנט][sentiment-api-docs] של טקסט במודעה – כולל הכותרת או התיאור. המדד הזה מאפשר להבין עד כמה המסר חיובי ומה העוצמה שלו. לדוגמה, מה עדיף: אנחנו מוכרים עוגות או אנחנו מוכרים את העוגות הכי טובות בלונדון. כדאי לקנות עוד היום!?

הגדרת הסקריפט
  1. יוצרים פרויקט חדש במסוף Google Cloud.
  2. מפעילים את [Natural Language API][natural-language-api].
  3. מפעילים את החיוב בפרויקט.
  4. [יצירה של חשבון שירות][create-service-account]. מורידים את קובץ ה-JSON של פרטי הכניסה.
  5. מדביקים את [הסקריפט לדוגמה][natural-language-example] בסקריפט חדש ב-Google Ads.
  6. בנוסף, מדביקים את [דוגמת ספריית OAuth2][oauth20-library-example] מתחת לרשימת הקוד.
  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

הספרייה 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() ולחזור על הפעולה לכל צאצא במקרים שבהם צפויים כמה צאצאים מסוג text.

דוגמה של Sportradar

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

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

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

  1. בקטע Applications (אפליקציות), לוחצים על Create a new Application (יצירת אפליקציה חדשה). נותנים לאפליקציה שם ותיאור, ומתעלמים משדה האתר.
  2. בוחרים רק באפשרות Issue a new key for Soccer Trial Europe v2 (הנפקת מפתח חדש למינוי Soccer Trial Europe v2).
  3. לוחצים על Register Application (רישום אפליקציה).

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

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

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

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

  • 404 Not Found מציין שהמשאב המבוקש לא קיים.

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

בדיקת הבקשות

בדיקת הבקשות שימושית כשהתשובות של ה-API מצביעות על כך שהבקשה לא תקינה, למשל, קוד סטטוס 400. כדי לבדוק בקשות, ל-UrlFetchApp יש שיטה נלווית לשיטה 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(), כדי לרשום ביומן גם בקשות וגם תשובות.

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

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

‫[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