שיטות מומלצות לשימוש בשירותי האינטרנט של Air Quality API

שירותי האינטרנט של הפלטפורמה של מפות Google הם אוסף של ממשקי HTTP של Google שירותים שמספקים נתונים גיאוגרפיים לאפליקציות המפות שלך.

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

מהו שירות אינטרנט?

שירותי האינטרנט של הפלטפורמה של מפות Google הם ממשק לבקשת נתונים של Maps API מ- שירותים חיצוניים ושימוש בנתונים שבאפליקציות שלך במפות Google. השירותים האלה לשימוש בשילוב עם מפה, הגבלות על רישיונות בתנאים ובהגבלות של הפלטפורמה של מפות Google.

שירותי האינטרנט של ממשקי ה-API של מפות Google משתמשים בבקשות HTTP(S) לכתובות URL ספציפיות, ומעבירים פרמטרים של כתובות אתרים ו/או נתוני POST בפורמט JSON כארגומנטים לשירותים. בדרך כלל, שירותים אלה מחזירים נתונים גוף התגובה כ-JSON לצורך ניתוח ו/או בעיבוד באמצעות הבקשה שלך.

שליחת בקשה לאיכות האוויר הנוכחית לפי שעה באמצעות currentConditions בנקודת קצה (endpoint) על ידי שליחת בקשת HTTP POST אל:

https://airquality.googleapis.com/v1/currentConditions:lookup?key=API_KEY

מעבירים גוף JSON לבקשה המגדירה את המיקום.

הערה: כל האפליקציות עם Air Quality API מחייבות אימות. מידע נוסף על פרטי כניסה לאימות

גישת SSL/TLS

צריך להשתמש ב-HTTPS בכל הבקשות לפלטפורמה של מפות Google שמשתמשות במפתחות API או מכילות נתוני משתמשים. בקשות שמבוצעות באמצעות HTTP ומכילות מידע אישי רגיש עשויות להידחות.

יצירת כתובת URL חוקית

אולי תחשבו שהערך 'חוקי' כתובת ה-URL ברורת לעצמו, זה לא בדיוק המקרה. כתובת URL שהוזנה בסרגל הכתובות הדפדפן, למשל, עשוי להכיל תווים מיוחדים (למשל "上海+中國"); הדפדפן צריך לתרגם באופן פנימי את התווים האלה לקידוד אחר לפני ההעברה. באופן דומה, כל קוד שיוצר או מקבל קלט ב-UTF-8 עשוי להתייחס לכתובות URL עם תווים ב-UTF-8 כ'תקינות', אבל יהיה עליו גם לתרגם את התווים האלה לפני השליחה שלהם לשרת אינטרנט. התהליך הזה נקרא קידוד כתובות URL או קידוד באחוזים.

זהירות: דפדפנים ו/או שירותים עשויים לבצע קידוד URL אוטומטי של מזהה ה-URI של הבקשה לפני השליחה. בממשקי API שמשתמשים בחתימת בקשות קריפטוגרפית, הפעולה הזו עשויה: עלולה לבטל את תוקף החתימה אם קידוד כתובת ה-URL משנה את הבקשה לאחר החתימה. כדי להימנע מקודדת את מחרוזת השאילתה תמיד בכתובת URL, לפני שחותמים על בקשה.

תווים מיוחדים

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

סיום	תווים	שימוש בכתובת URL
אלפאנומרי	a b c d f g h i j k l m. מ י ד י נ ת ח י ם A B C D E F G H I J K L M N O P Q R S T U W X Y Z 0 1 2 3 4 5 6 7 8 9	מחרוזות טקסט, שימוש בסכמה (http), יציאה (8080) וכו'.
לא שמור	- _ . ~	מחרוזות טקסט
בוצעה הזמנה	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	תווי בקרה ו/או מחרוזות טקסט

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

• תווים שבהם אתה רוצה לטפל קיימות מחוץ ל- ברמה גבוהה יותר. לדוגמה, תווים בשפות זרות, כמו 上海+中國, צריך לקודד באמצעות התווים שלמעלה. לפי הסכמה פופולרית, לעיתים קרובות רווחים (שאסור להשתמש בהם בכתובות URL) מיוצגים גם באמצעות התו '+'.
• התווים קיימים במסגרת הקבוצה שלמעלה כתווים שמורים, אבל צריך להשתמש בו באופן מילולי. לדוגמה, התו ? משמש בכתובות URL כדי לציין את תחילת מחרוזת השאילתה. אם רוצים להשתמש במחרוזת '? and the Mysterions', צריך לקודד את התו '?'.

כל התווים לקידודי התווים שמתאימים לכתובות URL מקודדים באמצעות תו '%' וקוד הקסדצימלי בן שני תווים שתואם לתו UTF-8 שלהם. לדוגמה, הקידוד של 上海+中國 בקידוד UTF-8 יתבצע בכתובת ה-URL כ- %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. המחרוזת ? and the Mysterians תהיה מקודדת בכתובת URL כך %3F+and+the+Mysterians או %3F%20and%20the%20Mysterians.

תווים נפוצים שדורשים קידוד

הנה מספר תווים נפוצים שחובה לקודד:

תו לא בטוח	ערך מקודד
רווח	%20
"	%22
<	%3C
>	%3E
#	%23
%	%25
|	%7C

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

בנוסף, כתובות ה-URL מוגבלות ל-16,384 תווים בכל שירותי האינטרנט של הפלטפורמה של מפות Google וממשקי API סטטיים לאינטרנט. ברוב השירותים שלרוב תתקרבו למגבלת התווים הזו. אבל, לפעמים חשוב לשים לב ששירותים מסוימים כוללים מספר פרמטרים שעשויים להוביל לכתובות URL ארוכות.

שימוש מנומס בממשקי API של Google

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

השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

במקרים נדירים, משהו יכול להשתבש בעת מילוי הבקשה שלכם; ייתכן שתקבלו קוד HTTP 4XX או 5XX קוד התגובה, או שחיבור ה-TCP עלול פשוט להיכשל במקום כלשהו בין הלקוח השרת. לרוב כדאי לנסות שוב את הבקשה, כי ייתכן שהבקשה הבאה תצליח אם הבקשה המקורית נכשלה. עם זאת, חשוב לא רק לבצע שוב ושוב בקשות לשרתים של Google. התנהגות הלולאה הזו עלולה לגרום לעומס ברשת בין הלקוח ל-Google, וכתוצאה מכך לבעיות אצל גורמים רבים.

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

לדוגמה, כדאי לבחון בקשה שרוצה להגיש את הבקשה הזו ממשק ה-API של אזור הזמן:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

הדוגמה הבאה ב-Python מראה איך לשלוח את הבקשה עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff):

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

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

בקשות מסונכרנות

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

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

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

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

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

עיבוד התשובות

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

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

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

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