بناء منطق التحقق من الصحة

يصف هذا المستند عملية إنشاء نظام للتحقّق من العناوين بهدف التعامل مع مجموعة متنوعة من الردود الواردة من 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 إلى عدم توفّر معلومات مهمة يجب تقديمها. قد لا يكون العنوان الذي تعرضه واجهة برمجة التطبيقات Address Validation API بجودة تسمح بتسليم الرسائل إليه. سير العمل تحقّق من مكونات العنوان إذا لزم الأمر. اطلب من العميل حلّ المشاكل المتعلّقة بالعنوان. اطلب التحقّق من صحة العنوان المعدَّل. (اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات لواجهة برمجة التطبيقات. يُرجى الاطّلاع على معالجة العناوين المعدَّلة. يُرجى المتابعة باستخدام العنوان. إشارات البيان أيّ مما يلي ينطبق عليك: تم ضبط 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 API مجموعة متنوعة من الإشارات التي يمكنك دمجها مع مستوى المخاطر لتحسين عملية التحقّق من صحة البيانات. على سبيل المثال، إذا كان العنوان يتضمّن رقم شارع غير مؤكَّد، يمكنك قبوله. من ناحية أخرى، إذا كانت عملية نشاطك التجاري تتطلّب دقّة أكبر في العنوان، يمكنك أن تطلب من المستخدم تقديمه. للحصول على مثال يمكن أن يقع ضمن أيّ من الفئتَين، اطّلِع على رقم شارع غير مؤكَّد خارج الولايات المتحدة في قبول العنوان - أمثلة.
قبول العناوين	من الممارسات الجيدة السماح لنظامك بقبول الإدخال الأصلي إذا لم يردّ العميل على الطلبات.	في هذه الحالات، قد يكون العميل قد أدخل عنوانًا غير مُدرَج في النظام، مثل عنوان مبنى جديد.
إدخال تعليق	عند إعادة إصدار طلب التحقّق من العنوان، يمكنك أيضًا إرسال طلب إلى نقطة نهاية provideValidationFeedback.	يتيح ذلك لفريق Google معرفة كيفية تعاملك مع الردّ النهائي. يُرجى الاطّلاع على معالجة العناوين المعدَّلة.

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

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

ملاحظة: يجب مراعاة مستوى المخاطر عند تحديد ما إذا كان يجب تأكيد العنوان مع العميل أو قبوله على أنّه صالح. بالإضافة إلى ذلك، في حال إعادة إصدار طلبات إلى Address Validation API، يمكنك إجراء مكالمة إلى provideValidationFeedback للإشارة إلى النتيجة. اطّلِع على تعديل عنوان البريد الإلكتروني المرتبط بحسابك.

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

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

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

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

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

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

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

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

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

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

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

قبول عنوان

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

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

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

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

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

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

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

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

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

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

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

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