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

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

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

תיקון כתובת

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

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

תיקון האותות

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

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

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

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

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

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

רכיבים חשודים	כשרמת האישור של רכיב מסוים היא 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 בכתובות בארצות הברית.

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