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

מטרה

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

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

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

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

בדיקה

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

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

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

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

אם התגובה של 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

הטמעת אימות כתובות ללא רכיב ראשי (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. אם הכתובת איכותית, ה-Address Validation API מחזיר את הערך formattedAddress.
  5. אם בוצעו תיקונים, תוכלו להציג את הכתובת הזו למשתמש. אם לא בוצעו תיקונים, תוכלו לאשר אותה בשקט.
  6. אחרי שהמשתמש יאשר, תוכלו לשמור את formattedAddress במטמון במסד הנתונים.

סיכום

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

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

השלבים הבאים

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

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

תורמים

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

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