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

هذا المنتج أو الميزة في مرحلة المعاينة (ما قبل الإصدار العام). قد يكون الدعم المقدّم للمنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام متوافقة مع الإصدارات الأخرى من هذه المرحلة. تخضع "عروض مرحلة ما قبل التوفّر للجمهور العام" لبنود الخدمة المحدّدة في "منصة خرائط Google". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

يوضّح هذا المستند عملية إنشاء نظام للتحقّق من العناوين بهدف التعامل مع مجموعة متنوعة من الردود من 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 في JavaScript لخرائط Google.

تصحيح عنوان

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

إصلاح الإشارات

توفّر واجهة برمجة التطبيقات 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، راجِع التعامل مع العناوين في الولايات المتحدة.

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