דף זה תורגם על ידי Cloud Translation API.

ממשקי 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. לשם כך, משתמשים ב-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);

דוגמה מורחבת ל-Slack

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

הודעה נכנסת

למידע נוסף על הודעות ב-Slack, אפשר לעיין במאמר עיצוב הודעות במסמכי העזרה של Slack.

נתוני טופס

בדוגמה שלמעלה מוצג שימוש במחרוזת JSON כנכס payload לבקשה POST.

בהתאם לפורמט של payload, ל-UrlFetchApp יש גישות שונות ליצירת הבקשה POST:

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

בחלק מ-APIs נדרש שימוש בנתוני טפסים כששולחים בקשות POST, לכן כדאי לזכור את ההמרה האוטומטית מאובייקטי JavaScript לנתוני טפסים.

אימות בסיסי של HTTP

אימות HTTP בסיסי הוא אחת מהצורות הפשוטות ביותר של אימות, וממשקי API רבים משתמשים בו.

האימות מתבצע על ידי צירוף שם משתמש וסיסמה מוצפנים לכותרות ה-HTTP בכל בקשה.

אימות בסיסי של HTTP

בניית בקשה

כדי ליצור בקשה מאומתת, צריך לבצע את השלבים הבאים:

כדי ליצור את ביטוי הגישה, משלבים את שם המשתמש והסיסמה באמצעות פסיק נקודה, לדוגמה username:password.
מקודדים את ביטוי הסיסמה ב-Base64. לדוגמה, username:password הופך ל-dXNlcm5hbWU6cGFzc3dvcmQ=.
מצרפים לבקשה כותרת Authorization, בפורמט Authorization: Basic <encoded passphrase>

קטע הקוד הבא מדגים איך לעשות זאת ב-Google Ads Scripts:

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 בתסריט לאחד ממספרי ה-sandbox שרשומים עכשיו. המספר צריך לכלול את קידומת המדינה הבינלאומית, למשל 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 Core. כדאי לעיין במיוחד בקטע 6. אימות באמצעות OAuth. בתהליך שלוש-רגלי מלא של OAuth 1.0, התהליך הוא:

האפליקציה ('הצרכן') מקבלת אסימון בקשה.
המשתמש מאשר את טוקן הבקשה.
האפליקציה ממירה את טוקן הבקשה לטוקן גישה.
בכל בקשות המשאבים הבאות, אסימון הגישה משמש בבקשה חתומה.

כדי ששירותים של צד שלישי יוכלו להשתמש ב-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.

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

בסקריפט

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

שליחת בקשות 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, כולל:

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

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 שאפשר להשתמש בו עם אסימון רענון. בדוגמה הזו, סקריפט יוצר דוח ומחזיר אותו. בחומר העזר בנושא Search Ads 360 API מפורטים פרטים מלאים על פעולות אחרות שאפשר לבצע.

יצירת הסקריפט

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

דוגמה לממשק API לביצוע סקריפט של Apps Script

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

יצירת הסקריפט של Google Ads

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

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

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

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

דוגמה ל-Google Natural Language API

Natural Language API מספק ניתוח סנטימנט וניתוח ישויות לטקסט.

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

הגדרת הסקריפט

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

הגדרת חשבון Sportradar

עוברים אל האתר למפתחים של Sportradar.
נרשמים לחשבון לניסיון.
אחרי ההרשמה, נכנסים לחשבון.
אחרי הכניסה, עוברים אל MyAccount.

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

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

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

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

פתרון בעיות

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

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

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

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

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

מחליפים את כל המופעים של 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;
}

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