إنشاء منطق التحقّق

يصف هذا المستند عملية إنشاء نظام للتحقّق من العناوين من أجل التعامل مع مجموعة متنوعة من الردود من Address Validation 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 إلى أنّ هناك معلومات مهمة ناقصة يجب تقديمها. قد لا يكون العنوان الذي تعرضه واجهة برمجة التطبيقات بجودة قابلة للتسليم. سير العمل تحقَّق من مكوّنات العنوان إذا لزم الأمر. اطلب من العميل حلّ المشاكل المتعلّقة بالعنوان. اطلب التحقّق من صحة العنوان المعدَّل. يُرجى المتابعة باستخدام العنوان. إشارات التحقّق أيّ مما يلي: تم ضبط validationGranularity على OTHER. addressComplete هو false.
تأكيد العنوان	يشير الردّ من verdict إلى عنوان قابل للتسليم، ولكن تم إجراء تغييرات على الإدخال الأصلي: استنتاج البيانات التي تم تصحيحها إملائيًا أو البيانات التي يمكن تأكيدها. سير العمل التصحيحات المطلوبة: تحقَّق من مكوّنات العنوان إذا لزم الأمر. اطلب التحقّق من صحة العنوان المعدَّل. يُرجى المتابعة باستخدام العنوان. لا حاجة إلى إجراء أي تصحيحات: يُرجى المتابعة باستخدام العنوان. إشارات التحقّق جميع الشروط التالية: validationGranularity يحتوي على ROUTE addressComplete هو true. hasInferredComponents هو true أو hasReplacedComponents هو true.
قبول العنوان	يشير ردّ من واجهة برمجة التطبيقات Address Validation API إلى عنوان عالي الجودة. سير العمل المتابعة باستخدام العنوان الذي تم عرضه إشارات التحقّق جميع الشروط التالية: يحتوي validationGranularity على PREMISE أو أفضل. addressComplete هو true. لا يتم استنتاج المكوّنات أو استبدالها.

إرشادات التنفيذ

عند تصميم طريقة استجابة نظامك لإشارات التحقّق من العناوين، يمكن أن تساعدك الاقتراحات التالية في إنشاء نموذج استجابة أكثر فعالية. ومع ذلك، هذه مجرد اقتراحات، لذا يجب أن تضع في اعتبارك أن التنفيذ يجب أن يناسب نموذج عملك.

	الإرشادات	التفاصيل
مستوى الخطورة	يجب مراعاة مستوى التسامح مع الأخطاء في حالتك عند الموازنة بين طلب التصحيحات وقبول العنوان كما تم إدخاله.	تعرض واجهة Address Validation API مجموعة متنوعة من الإشارات التي يمكنك دمجها مع مستوى المخاطر لتحسين عملية التحقّق. على سبيل المثال، إذا كان العنوان يحتوي على رقم شارع غير مؤكّد، يمكنك قبوله. من ناحية أخرى، إذا كانت عملياتك التجارية تتطلّب دقة أكبر في العنوان، يمكنك أن تطلب من المستخدم إدخال عنوانه. للاطّلاع على مثال يمكن أن يندرج ضمن أيّ من الفئتَين، يُرجى مراجعة رقم شارع غير مؤكّد خارج الولايات المتحدة في قبول العنوان - أمثلة.
قبول العناوين	من الممارسات الجيدة السماح لنظامك بقبول الإدخال الأصلي إذا لم يستجب العميل للمطالبات.	في هذه الحالات، قد يكون العميل قد أدخل عنوانًا غير موجود في النظام، مثل عنوان مبنى جديد.

تجربة العرض التوضيحي يستخدم الجزء المتبقي من هذا المستند مجموعة متنوعة من الأمثلة لمساعدتك في فهم عملية الإصلاح والتأكيد والقبول الموضحة أعلاه. يمكنك استكشاف النتائج من هذه الأمثلة عن طريق إدخالها في النسخة التجريبية من Address Validation في Maps JavaScript API.

تصحيح عنوان

تصحيح عنوان عندما تشير النتائج بوضوح إلى أنّه لا يمكن تسليم الطلب إليه يمكن لنظامك بعد ذلك أن يطلب من العميل تقديم المعلومات اللازمة، وبعد ذلك يمكنك إعادة إصدار سير العمل للحصول على عنوان قابل للتسليم.

حلّ المشاكل في الإشارات

توفّر واجهة Address Validation API عددًا من الإشارات لإعلامك بما إذا كان يجب إصلاح عنوان معيّن.

1. دقة التحقّق من الصحة والمكوّنات غير المتوفّرة

توفّر هاتان الإشارتان أفضل مؤشر على عنوان يمثّل مشكلة:

• عندما يكون الحقل validationGranularity هو OTHER، على نظامك التحقيق في إشارات مكوّنات العنوان لمعرفة المزيد حول مكان حدوث الخطأ وكيفية حلّه.
• عندما يعرض عنصر address الذي تمت معالجته لاحقًا حقل missingComponentTypes، على نظامك التحقّق من هذا المكوّن. وتؤدي المكوّنات غير المتوفّرة أيضًا إلى جعل العنوان غير مكتمل وغير قابل للتسليم.

2. الإشارات الأخرى

توفّر Address Validation API أيضًا إشارات أخرى للمساعدة في تشخيص مشاكل معيّنة:

المكوّنات المريبة	عندما يكون تعداد مستوى التأكيد لمكوّن معيّن هو UNCOMFIRMED_AND_SUSPICIOUS، من المرجّح أن يكون المكوّن غير صحيح.
مكوّن لم يتم حلّه	unresolvedToken هو جزء من الإدخال لا يتم التعرّف عليه كجزء صالح من العنوان.

3- إشارات العنوان في الولايات المتحدة

توفّر بعض الحقول التي تنطبق فقط على العناوين في الولايات المتحدة إشارة مفيدة إلى أنّ العنوان غير قابل للتسليم ويجب إصلاحه. بالنسبة إلى العنوان الذي يتطلب إصلاحًا، من المفترض أن يظهر لك ما يلي:

dpvConfirmation	إما N أو D أو فارغ

لمعرفة التفاصيل حول dpvConfirmation، يُرجى الاطّلاع على مقالة التعامل مع العناوين في الولايات المتحدة.

أمثلة على تصحيح العناوين

تأكيد عنوان

يمكنك تأكيد عنوان عندما يشير القرار إلى أنّ Address Validation API قد استنتجت أو أجرت تغييرات على مكوّنات العنوان لإنشاء عنوان تم التحقّق منه. في هذه الحالات، يكون لديك عنوان قابل للتسليم، ولكنّك تفضّل زيادة الثقة في أنّ العنوان الناتج هو العنوان الذي يقصده العميل.

لتزويد العميل بالطلب الصحيح، سيحدّد المنطق الخاص بك المكوّنات التي تم وضع علامة عليها من قِبل الخدمة لتحديد الإجراء أو العلامة التي طبّقتها واجهة برمجة التطبيقات على المكوّن، مثل inferred أو replaced أو spellCorrected. اطّلِع على AddressComponent في المرجع.

ملاحظة: يجب مراعاة مستوى المخاطر عند تحديد ما إذا كان يجب تأكيد العنوان مع العميل أو قبوله كعنوان صالح.

تأكيد الإشارات

توفّر واجهة Address Validation API عددًا من الإشارات لإعلامك بما إذا كان يجب تأكيد العنوان.

1. دقة التحقّق

يُعدّ validationGranularity من ROUTE أو أفضل مقبولاً، ولكن يوفّر PREMISE أو SUBPREMISE إشارة أقوى على إمكانية التسليم.

2. الإشارات الأخرى

عند اتخاذ قرار بتأكيد إدخال العنوان مع العميل، يوفّر القرار أيضًا ما يلي لتحديد المكوّنات التي يجب التحقيق فيها:

البيانات المستنتَجة	عندما تكون قيمة الحقل hasInferredComponents هي true، يعني ذلك أنّ واجهة برمجة التطبيقات قد ملأت المعلومات التي جمعتها من مكوّنات العناوين الأخرى.
البيانات التي تم استبدالها	عندما يكون الحقل hasReplacedComponents هو true، تستبدل واجهة برمجة التطبيقات البيانات التي تم إدخالها ببيانات تعتبرها صالحة للعنوان.

3- إشارات العنوان في الولايات المتحدة

تشير بعض الحقول التي تنطبق فقط على العناوين في الولايات المتحدة إلى أن منطقك يجب أن يؤكد التفاصيل مع العميل. ينطبق أيّ مما يلي:

dpvConfirmation	S لمعرفة التفاصيل حول dpvConfirmation، يُرجى الاطّلاع على التعامل مع العناوين في الولايات المتحدة.
Address response	يحتوي على حقل missingComponentTypes بقيمة subpremise. ملاحظة: إذا كان الحقل يحتوي على أنواع غير subpremise، سيتم إدراج الإجراء ضمن فئة تصحيح العنوان. يمكنك الاطّلاع على القائمة الكاملة لأنواع العناوين في مستندات الترميز الجغرافي.

أمثلة على تأكيد العنوان

قبول عنوان

يمكنك قبول عنوان عندما يوفّر القرار درجة عالية من الثقة بأنّ العنوان قابل للتسليم ويمكن استخدامه بدون أي تفاعل إضافي من العميل في العملية اللاحقة.

قبول الإشارات

توفّر واجهة Address Validation API عددًا من الإشارات لإعلامك بما إذا كان يجب تأكيد العنوان.

1. دقة التحقّق

يُعدّ validationGranularity من PREMISE أو أفضل مقبولاً، ولكن في بعض الحالات، لا يزال ROUTE يشير إلى عنوان قابل للتسليم.

2. الإشارات الأخرى

يجب أن يوفّر القرار بشأن عنوان عالي الجودة ما يلي أيضًا:

• عدم استبدال البيانات: في هذه الحالة، hasReplacedComponents: FALSE.
• ما مِن مكوّنات مستنتَجة. في هذه الحالة، hasInferredComponents: FALSE.

3- إشارات العنوان في الولايات المتحدة

تشير بعض الحقول التي تنطبق فقط على العناوين في الولايات المتحدة إلى عنوان عالي الجودة يمكن التسليم إليه. بالنسبة إلى عنوان مقبول في الولايات المتحدة، من المفترض أن يظهر لك ما يلي:

dpvConfirmation	Y لمعرفة تفاصيل حول dpvConfirmation، يُرجى الاطّلاع على التعامل مع العناوين في الولايات المتحدة.

أمثلة على العناوين المقبولة