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

מטרה

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

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

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

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

בדיקה

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

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

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

אימות כתובות באופן קבוע

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

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

ניתוח מעמיק של הנתונים הטכניים

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

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

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

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

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

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

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

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

אם המשתמש נתן את הסכמתו, אפשר לשמור במטמון את formattedAddress ורכיבים מרכזיים אחרים מהתשובה. עם זאת, בתרחיש ללא 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 עם הכתובת הקיימת. ה-API לאימות כתובת יחזיר את הכתובת המתוקנת, שאותה אפשר להציג באמצעות הנחיה בממשק המשתמש. אחרי שהלקוח יאשר את הכתובת בפורמט הרצוי, תוכלו לשמור במטמון את הפרטים הבאים מהתגובה:

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

הטמעת אימות כתובות ללא רכיב ראשי (headless)

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

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

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

שלב 1:

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

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

alt_text

בהתאם לתנאים ולהגבלות, אפשר לשמור במטמון את הנתונים הבאים מה-addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

לכן, בשלב הזה של ההטמעה נסגור במטמון את השדות שצוינו למעלה בהתאם ל-User-ID.

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

שלב 2:

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

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

alt_text

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

סיכום

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

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

השלבים הבאים

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

מקורות מידע נוספים:

תורמים

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

Henrik Valve | מהנדס פתרונות
Thomas Anglaret | מהנדס פתרונות
Sarthak Ganguly | מהנדס פתרונות