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

تصف هذه المستند عملية إنشاء نظام للتحقّق من العناوين من أجل معالجة مجموعة متنوّعة من الردود من 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، راجِع معالجة العناوين في الولايات المتحدة.
ردّ العنوان	يحتوي على الحقل missingComponentTypes بقيمة subpremise. ملاحظة: إذا كان الحقل يحتوي على أنواع أخرى غير subpremise، سيندرج الإجراء ضمن فئة إصلاح العنوان. راجِع القائمة الكاملة لأنواع العناوين في مستندات الترميز الجغرافي.

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

قبول عنوان

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

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

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

1. دقة التحقّق من صحة العنوان

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

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

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

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

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

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

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

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