שיטות מומלצות לשימוש בשירותי אינטרנט של Roads API

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

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

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

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

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

בקשה לשירות אינטרנט של API של Roads בדרך כלל היא אחת מהדרכים הבאות:

https://roads.googleapis.com/v1/snapToRoads?parameters&key=YOUR_API_KEY

כאשר snapToRoads מציין את השירות הספציפי המבוקש. שירותים אחרים בכבישים כוללים את nearestRoads ואת speedLimits.

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

גישת SSL/TLS

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

בניית כתובת URL חוקית

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

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

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

הגדרה	תווים	שימוש בכתובת URL
אלפאנומרי	מ ח ל ו ן	מחרוזות טקסט, שימוש בסכימה (http), יציאה (8080) וכו'.
לא שמור	- _ . ~	מחרוזות טקסט
בוצעה הזמנה	! * ' ( ) ; : @ & = + $ , / ? % # [ ]	תווי בקרה ו/או מחרוזות טקסט

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

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

כל התווים בקידוד כתובת URL מקודדים בתו '%' ובערך הקסדצימלי של שני תווים שתואם לתו UTF-8 שלהם. לדוגמה, הקידוד של 上海+中國 ב-UTF-8 הוא %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 שאתם מקבלים מקלט של משתמש. לדוגמה, משתמש עשוי להזין את הכתובת 'רחוב חמישי וראשי' באופן כללי, צריך לבנות את כתובת האתר מהחלקים שלה ולהתייחס לכל קלט של משתמש כאל תווים מילוליים.

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

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

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

השהיה מעריכית

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

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

לדוגמה, נניח שיש לכם בקשה לשלוח את הבקשה הזו ל-Time Zone API:

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

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

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}")

כמו כן, חשוב לוודא שאין ניסיון חוזר בקוד ברשת של הבקשות, שמוביל לבקשות חוזרות ברצף מהיר.

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

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

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

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

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

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

עיבוד תגובות

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

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

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

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