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

במסמך הזה מתוארים תהליך לפיתוח מערכת לבדיקת כתובות לטיפול במגוון תגובות מ-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 או יותר. לראות את ערכי granularity. addressComplete true. השדה hasInferredComponents הוא true או השדה hasReplacedComponents הוא true.
אישור הכתובת	תגובת ה-API לאימות כתובת מציינת כתובת באיכות מצוינת. תהליך עבודה ממשיכים עם הכתובת להחזרת מוצרים. אותות לגבי תוצאות כל התנאים הבאים חלים: validationGranularity מכיל PREMISE או יותר. הצגת ערכי granularity 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 זמינים במאמר טיפול בכתובות בארה"ב.

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

אישור כתובת

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

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

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

אישור האותות

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

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

הערך של validationGranularity יכול להיות ROUTE או יותר, אבל הערך של validationGranularity ב-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 זמינים במאמר טיפול בכתובות בארה"ב.

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