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

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

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

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

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

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

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

כדי לאמת כתובת, שולחים בקשת POST HTTP ל-method VerifyAddress:

https://addressvalidation.googleapis.com/v1:validateAddress

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

הערה: כל האפליקציות של ממשק ה-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 e 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 X Y Z 3 0 1 2 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, ולגרום לבעיות רבות אצל גורמים רבים.

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

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