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

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

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

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

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

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

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

בקשה אופיינית לשירות אינטרנט של Roads API היא בדרך כלל בצורה הבאה:

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

סיכום של תווים חוקיים של כתובת URL

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

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

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

כל התווים לקידוד כתובת 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 שמקבלים מקלט של משתמשים. לדוגמה, משתמש יכול להזין כתובת כ"רחוב ראשי וחמישי". באופן כללי, מומלץ ליצור את כתובת ה-URL מהחלקים שלה, ולהתייחס לכל קלט של משתמש כאל תווים מילוליים.

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

שימוש מנומס ב-Google APIs

לקוחות 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}")

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

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

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

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

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

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

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

מתבצע עיבוד של התשובות

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

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

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