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

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

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

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

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

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

בקשות למיקום גיאוגרפי נשלחות באמצעות POST לכתובת ה-URL הבאה:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

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

גישת SSL/TLS

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

שימוש מנומס ב-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 עצמו בלקוח.