שימוש ב-Address Authentication API לעיבוד כתובות בנפח גבוה

יעד

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

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

תרחישים לדוגמה

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

בדיקה

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

אימות חד-פעמי של כתובות

כשמתחילים להשתמש ב-Address Validation API, רוצים לאמת את מסד הנתונים הקיים של הכתובות מול מסד הנתונים של המשתמשים.

אימות חוזר של כתובות

יש מספר תרחישים דורשים אימות כתובות על בסיס קבוע:

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

ניתוח טכני מפורט

למטרות המסמך הזה, אנחנו מניחים כי:

  • בחרת להפעיל את Address Validation API עם כתובות ממסד נתונים של לקוחות (כלומר מסד נתונים עם פרטי לקוח)
  • ניתן לשמור במטמון סימונים של תוקף כתובות ספציפיות במסד הנתונים.
  • סימונים של אימות מאוחזרים מה-Address Validation API כשלקוח נכנס לחשבון.

שמירה במטמון לשימוש בסביבת הייצור

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

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

  • נתונים מהאובייקט AddressComponent
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

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

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

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

הסבר על התשובה

אם התשובה של Address Validation API מכילה את הסמנים הבאים, באפשרותך להיות בטוחים שכתובת הקלט היא באיכות שבה ניתן להעברה:

  • הסמן addressComplete באובייקט Verdict הוא true,
  • ה-validationGranularity באובייקט Verdict הוא PREMISE או SUB_PREMISE
  • אף אחד מה-AddressComponent לא מסומן בתור:
    • Inferred(הערה: inferred=trueיכול להיות שהפעולה תתבצע כאשר addressComplete=true)
    • spellCorrected
    • replaced
    • unexpected, וגם
  • confirmationLevel: רמת האישור בקטע AddressComponent מוגדרת כ-CONFIRMEDאוUNCONFIRMED_BUT_PLAUSIBLE

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

  • formattedAddress
  • postalAddress
  • addressComponent componentNames או
  • UspsData standardizedAddress

הטמעת אימות כתובת ללא GUI

בהתאם לדיון שלמעלה:

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

בקטע הבא נדון בתהליך דו-שלבי לגבי הציות לתנאים ולהגבלות והטמעת אימות של כמות גדולה של כתובות.

שלב 1:

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

תרשים א': בתרשים הבא אפשר לראות איך אפשר לשפר את צינור עיבוד הנתונים באמצעות לוגיקה לאימות כתובות בנפח גבוה.

alt_text

  • לפי התנאים וההגבלות , אפשר לשמור במטמון addressComplete, validationGranularity and validationFlags כשמאמתים כתובות ללא GUI.

  • אפשר לשמור את addressComplete,validationGranularity and validationFlags, PlaceID במטמון עם מזהה משתמש ספציפי במסד הנתונים של הלקוחות.

לכן, בשלב הזה של ההטמעה, נשמור את השדות המפורטים למעלה ב-UserID.

למידע נוסף, ניתן לעיין בפרטים על מבנה הנתונים בפועל.

שלב 2:

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

תרשים ב': בתרשים הזה אפשר לראות איך שילוב של תהליך קבלת ההסכמה מקצה לקצה עשוי להיראות כך:

alt_text

  1. כשהמשתמש מתחבר לחשבון, בודקים קודם אם שמרתם במערכת דגלי אימות כלשהם, כמו:

    • addressComplete נכון
    • validationGranularity אינו PREMISE או SUB_PREMISE
    • validationFlags הוא inferred,spellCorrected,replaced,unexpected.
      • אם אין סימונים, סביר להניח שהכתובת הקיימת שנשמרה במטמון היא באיכות טובה וניתן להשתמש בה.

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

  3. אפשר להפעיל שוב את Address Validation API עם הכתובת המעודכנת או השמורה במטמון ולהציג למשתמש את הכתובת המתוקנת כדי לאשר את הפעולה.

  4. אם הכתובת איכותית, ה-Address Validation API מחזיר את הערך formattedAddress.

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

  6. לאחר שהמשתמש יאשר את ההזמנה, ניתן יהיה לשמור את formattedAddress במטמון במסד הנתונים.

הטמעת קוד פסאודו בשלב 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

סיכום

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

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

השלבים הבאים

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

הצעות נוספות לקריאה:

תורמים

Google מנהלת את המאמר הזה. תורמי התוכן הבאים כתבו אותו במקור.
המחברים הראשיים:

Henrik Valve | מהנדס פתרונות
תומאס אנגלרט | מהנדס פתרונות
סרתק גנגולי | מהנדס פתרונות