בניית הלוגיקה של האימות

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

באופן כללי, התגובה מה-API קובעת את הדרכים הבאות שבהן המערכת צריכה לטפל בכתובת:

• handyman תיקון – הכתובת באיכות נמוכה. צריך לבקש מידע נוסף.
• edit אישור – הכתובת באיכות גבוהה אבל עם שינויים בכתובת הקלט. יכול להיות שתוצג בקשה לאישור.
• check אישור – הכתובת באיכות גבוהה. ניתן לאשר את הכתובת שצוינה.

מטרת המפתח

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

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

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

סקירה כללית של תהליך העבודה

בטבלה הבאה מפורטות שתי פעולות שאפשר לבצע במערכת:

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

התנהגות המערכת
handyman תיקון הכתובת	התשובה מה-verdict מציינת מידע חשוב חסר שצריך לספק. יכול להיות שהכתובת שתוחזר על ידי API לאימות כתובות לא תהיה באיכות שמתאימה לשליחה. תהליך עבודה אם צריך, בודקים את רכיבי הכתובת. מבקשים מהלקוח לפתור את הבעיות. מבקשים אימות של הכתובת המעודכנת. (אופציונלי) שולחים בקשה לנקודת הקצה של המשוב של ה-API. איך מטפלים בכתובות שעודכנו ממשיכים בציון הכתובת. אותות לגבי תוצאות אחד מהמצבים הבאים רלוונטי: validationGranularity הוגדרה לערך OTHER. ערכי רמת פירוט addressComplete false.
edit אישור הכתובת	התשובה מ-verdict מציינת כתובת שניתן להעביר, אבל ביצעה שינויים בקלט המקורי: הסקת נתונים שתוקנו או שניתן לאמת נתונים. תהליך עבודה תיקונים נדרשים: אם צריך, בודקים את רכיבי הכתובת. מבקשים אימות של הכתובת המעודכנת. (אופציונלי) שולחים בקשה לנקודת הקצה של המשוב של ה-API. טיפול בכתובות מעודכנות ממשיכים עם הכתובת. אין צורך בתיקונים: (אופציונלי) שולחים בקשה לנקודת הקצה של המשוב של ה-API. טיפול בכתובות מעודכנות ממשיכים עם הכתובת. אותות לגבי תוצאות כל התנאים הבאים חלים: validationGranularity מכיל ROUTE או יותר. לראות את ערכי granularity. addressComplete true. השדה hasInferredComponents הוא true או השדה hasReplacedComponents הוא true.
check אישור הכתובת	תגובת ה-API לאימות כתובת מציינת כתובת באיכות מצוינת. תהליך עבודה ממשיכים עם הכתובת להחזרת מוצרים. אותות לגבי תוצאות כל התנאים הבאים חלים: validationGranularity מכיל PREMISE או יותר. ערכי רמת פירוט addressComplete היא true. אין רכיבים משוערים או שהוחלפו.

הדרכה בנושא הטמעה

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

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

תיקון כתובת

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

תיקון האותות

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

1. רמת פירוט האימות והרכיבים החסרים

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

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

2. אותות אחרים

ב-Address Validation API יש גם אותות אחרים שעוזרים לאבחן בעיות ספציפיות:

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

3. אותות של כתובות בארה"ב

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

dpvConfirmation	הערך יכול להיות N,‏ D או ריק.

פרטים על dpvConfirmation זמינים במאמר טיפול בכתובות בארה"ב.

דוגמאות לתיקון כתובות

אישור כתובת

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

כדי לספק ללקוח את ההנחיה הנכונה, הלוגיקה תזהה את הרכיבים שסומנו על ידי השירות כדי לקבוע איזו פעולה או תג ה-API הוחלו על הרכיב, כמו inferred,‏ replaced או spellCorrected. מידע נוסף זמין במאמר AddressComponent.

אישור האותות

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

1. רמת פירוט האימות

הערך של validationGranularity יכול להיות ROUTE או יותר, אבל הערך של validationGranularity ב-PREMISE או ב-SUBPREMISE מספק אות חזק יותר לגבי יכולת המסירה.

2. אותות אחרים

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

נתונים משוערים	כשהשדה hasInferredComponents הוא true, זה אומר שה-API מילא מידע שצבר מרכיבי כתובת אחרים.
הנתונים שהוחלפו	כשהשדה hasReplacedComponents הוא true, ה-API מחליף את הנתונים שהוזנו בנתונים שהוא סבר שהם יהפכו את הכתובת לתקינה.

3. אותות של כתובות בארה"ב

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

dpvConfirmation	S פרטים על dpvConfirmation זמינים במאמר טיפול בכתובות בארה"ב.
תגובה לכתובת	מכיל את השדה missingComponentType עם הערך subpremise.

דוגמאות לכתובות לאישור

אישור כתובת

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

אישור אותות

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

1. רמת הפירוט של האימות

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

2. אותות אחרים

חוות דעת על כתובת באיכות גבוהה צריכה לכלול גם את הפרטים הבאים:

• אין נתונים שהוחלפו. במקרה הזה, hasReplacedComponents: FALSE.
• אין רכיבים משוערים. במקרה הזה, hasInferredComponents: FALSE.

3. אותות של כתובות בארה"ב

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

dpvConfirmation	Y לפרטים על dpvConfirmation אפשר לעיין במאמר טיפול בכתובות בארצות הברית.

דוגמאות לכתובות שאפשר לאשר