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

יעד

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

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

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

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

בדיקה

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

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

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

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

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

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

ניתוח טכני מעמיק

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שלב 1:

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

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

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

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

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

שלב 2:

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

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

alt_text

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

סיכום

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

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

השלבים הבאים

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

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

תורמים

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

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