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

מטרה

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

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

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

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

בדיקה

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

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

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

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

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

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

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

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

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

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

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

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

הטמעה של אימות כתובת ללא ממשק משתמש

על סמך הדיון שלמעלה:

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

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

שלב 1:

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

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

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

לכן, במהלך השלב הזה של ההטמעה, נשמור במטמון את השדות שצוינו למעלה ביחס ל-UserID.

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

שלב 2:

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

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

alt_text

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

סיכום

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

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

השלבים הבאים

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

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

תורמים

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

Henrik Valve | Solutions Engineer
Thomas Anglaret | Solutions Engineer
Sarthak Ganguly | Solutions Engineer