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

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

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

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

الغرض الرئيسي

يساعدك هذا المستند في تعديل نظامك لتحليل استجابة واجهة برمجة التطبيقات و لتحديد الإجراءات التالية التي ينبغي اتخاذها مع العناوين المقدمة. ما يلي: يوضح الرمز الزائف التدفق المحتمل.

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.
قبول العنوان	تشير استجابة واجهة برمجة التطبيقات للتحقق من صحة العنوان إلى عنوان ممتاز. سير العمل يمكنك المتابعة بشأن العنوان الذي تم إرجاعه. إشارات البيان تنطبق جميع ما يلي: validationGranularity يحتوي على PREMISE أو أفضل. الاطّلاع على قيم درجة الدقة addressComplete true. لم يتم استنتاج أي مكوّنات أو استبدالها.

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

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

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

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

تصحيح عنوان

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

ملاحظة: عند تكرار الطلبات في واجهة برمجة تطبيقات التحقق من صحة العنوان الجغرافي للعنوان نفسه، يمكنك إجراء مكالمة إلى provideValidationFeedback لتحديد نتائجك. عرض التعامل مع العناوين في الولايات المتحدة

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

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

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

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

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

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

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

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

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

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

dpvConfirmation	حقل N أو D أو حقل فارغ.

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

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

تأكيد عنوان

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

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

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

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

توفر واجهة برمجة تطبيقات التحقق من صحة العنوان عددًا من الإشارات لإعلامك في حالة من العنوان.

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

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

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

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

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

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

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

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

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

قبول عنوان

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

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

توفر واجهة برمجة تطبيقات التحقق من صحة العنوان عددًا من الإشارات لإعلامك في حالة من العنوان.

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

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

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

يجب أيضًا أن يتضمن قرار الحصول على عنوان عالي الجودة ما يلي:

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

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

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

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

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