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

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

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

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

מטרת המפתח

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

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

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

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

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

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

תיקון כתובת

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

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

תיקון האותות

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

אישור האותות

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

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

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

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

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

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

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

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

dpvConfirmation	S פרטים על dpvConfirmation זמינים במאמר טיפול בכתובות בארה"ב.
תגובה לכתובת	מכיל את השדה missingComponentType עם הערך subpremise. הערה: אם השדה מכיל סוגים שונים מ-subpremise, הפעולה תסווג בקטגוריה 'תיקון כתובת'. רשימה מלאה של סוגי כתובות זמינה במסמכי העזרה בנושא גיאוקוד.

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

אישור כתובת

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

אישור אותות

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

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

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

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

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

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

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

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

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

דוגמאות לכתובות לקבלה