דף זה תורגם על ידי 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"

ה-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 שלא משנות את המצב בשלט הרחוק השרת משתמשים ב-HTTP GET .

השיטה GET היא ברירת המחדל של UrlFetchApp. עם זאת, בחלק מהקריאות ל-API, כמו שיחות לשירות ששולח הודעות SMS, יידרשו שיטות אחרות, כמו POST או PUT.

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

הגדרת Slack

המדריך הזה מבוסס על ההנחה שכבר נרשמתם לחשבון Slack.

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

להגדיר webhook נכנס על ידי לחיצה על מוסיפים שילוב Incoming WebHhooks ופועלים לפי ההוראות. צריך להפיק כתובת URL שתשמש להעברת הודעות.

שליחת בקשת POST

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

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

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

בנייה של בקשה

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

יוצרים את ביטוי הסיסמה על ידי צירוף שם המשתמש והסיסמה עם נקודתיים, למשל 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 חד-צדדי.

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 השונים לאחר מכן, ניתן יהיה להשתמש בהם בשאר הסשן כדי לאמת בקשות.

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

דפוס השימוש הכללי הוא:

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

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

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

דוגמה לממשק API לביצוע של Apps Script

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

שומרים את הסקריפט.
לוחצים על משאבים > פרויקט ב-Cloud Platform.
לוחצים על שם הפרויקט כדי לעבור אל מסוף ה-API.
מעבר אל APIs & שירותים.
מפעילים את ממשקי ה-API המתאימים, במקרה כזה Drive API, ו-Apps הפעלת הסקריפט API.
יוצרים פרטי כניסה של OAuth מהפריט Credentials בתפריט.
בחזרה לסקריפט, מפרסמים את הסקריפט להפעלה מפרסום > פריסה כניתן להפעלה של API.

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

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

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

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

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

דוגמה ל-Google Natural Language API

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

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

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

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

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 method:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

הקוד XmlService.parse מזהה שגיאות ב-XML וגורם חריגים לכן הוא לא מספק את היכולת לאמת את ה-XML מול של Google.

רכיב בסיס

בגלל שהניתוח של מסמך ה-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>

חשוב לשים לב איך מרחב השמות מצוין ברכיב הבסיסי (root). מהסיבה הזו נדרש כדי:

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

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

בקטע 'אפליקציות', לוחצים על יצירת אפליקציה חדשה. מתן הבקשה שם ותיאור, ומתעלמים משדה האתר.
בוחרים רק את Issue a new key new for Soccer team v2.
לוחצים על Register Application (רישום אפליקציה).

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

מדביקים את הסקריפט לדוגמה לסקריפט חדש ב-Google Ads.
מחליפים את מפתח ה-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);
// ...

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

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

לעזור בכל התהליך של בדיקת הבקשות והתשובות של צד שלישי, ניתן להשתמש בפונקציית העזרה הבאה במקום 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;
}

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