تمت ترجمة هذه الصفحة بواسطة Cloud Translation 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.

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

نظرة عامة على سير العمل

يلخّص الجدول التالي إجراءَين لنظامك:

سير العمل الذي يجب استخدامه استنادًا إلى حلّ المشكلة، والتأكيد، وقبولها.
الإشارات الأولى التي يجب التحقّق منها من الردّ. إنّ الإشارات الموضّحة هنا تأتي من السمة verdict وهي ليست الإشارات الوحيدة التي يجب التحقّق منها، ولكنها توفّر مؤشرًا أوليًا لجودة العنوان. يتوافق كل نوع سلوك مع قسم في هذا المستند يصف المزيد من الإشارات التي قد تحتاج أيضًا إلى التحقق منها.

سلوك النظام

تصحيح العنوان

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

سير العمل

تحقق من مكونات العنوان إذا لزم الأمر.
مطالبة العميل بحل المشاكل المتعلقة بحل المشاكل.
اطلب التحقق من العنوان الذي تم تعديله.
(اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات لواجهة برمجة التطبيقات. يُرجى الاطّلاع على التعامل مع العناوين المعدّلة.
يُرجى المتابعة باستخدام العنوان.

إشارات البيان

أي مما يلي ينطبق:

تم ضبط validationGranularity على ‎OTHER. راجِع قيم درجة الدقة.
قيمة addressComplete هي false.

تأكيد العنوان

يشير الردّ من verdict إلى عنوان تسليم، ولكنّه أجرى تغييرات على الإدخال الأصلي، وهو استنتاج بيانات تم تصحيحها إملائيًا أو بيانات يمكن تأكيدها.

سير العمل

التصحيحات المطلوبة:
1. تحقق من مكونات العنوان إذا لزم الأمر.
2. اطلب التحقق من العنوان الذي تم تعديله.
3. (اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات لواجهة برمجة التطبيقات. يُرجى الاطّلاع على التعامل مع العناوين المعدّلة.
4. يُرجى المتابعة باستخدام العنوان.
لا حاجة إلى أي تصحيحات:

(اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات لواجهة برمجة التطبيقات. يُرجى الاطّلاع على التعامل مع العناوين المعدّلة.
يُرجى المتابعة باستخدام العنوان.

إشارات البيان

ينطبق كل ما يلي:

validationGranularity يحتوي على ROUTE أو أفضل. راجِع قيم درجة الدقة.
قيمة addressComplete هي true.
القيمة الحالية للحقل hasInferredComponents هي true أو الحقل hasReplacedComponents هو true.

قبول العنوان

تشير استجابة واجهة برمجة التطبيقات التحقّق من صحة العناوين إلى أنّ العنوان ممتاز.

سير العمل

يمكنك المتابعة وتقديم العنوان الذي تم إرجاعه.

إشارات البيان

ينطبق كل ما يلي:

validationGranularity يحتوي على PREMISE أو أفضل. الاطّلاع على قيم درجة الدقة
قيمة addressComplete هي true.
لم يتم استنتاج أي مكوّنات أو استبدالها.

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

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

الإرشادات التفاصيل

مستوى المخاطر

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

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

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

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

قبول العناوين

ومن الممارسات الجيدة السماح للنظام بقبول البيانات الأصلية في حال عدم ردّ العميل على الطلبات.

في هذه الحالات، قد يكون العميل قد أدخل عنوانًا ليس في النظام، مثل عنوان لمبنى جديد.

تقديم ملاحظات وآراء

عند إعادة إصدار طلب التحقق من العنوان، يمكنك أيضًا إرسال طلب إلى نقطة النهاية provideValidationFeedback.

يتيح هذا الإجراء لـ Google معرفة كيفية تعاملك مع الردّ النهائي. يُرجى الاطّلاع على التعامل مع العناوين المعدّلة.

تصحيح عنوان

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

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

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

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

وتقدم هاتان الإشارتان أفضل مؤشر على العنوان الذي يواجه المشكلة:

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

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

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

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

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

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

`dpvConfirmation`	إما `N` أو `D` أو فارغة.

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

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

تأكيد عنوان

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

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

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

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

1- درجة دقة التحقق من الصحة

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

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

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

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

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

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

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

dpvConfirmation

S

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

الردّ على العنوان

يحتوي على حقل missingComponentType بقيمة subpremise.

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

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

قبول عنوان

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

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

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

1- درجة دقة التحقق من الصحة

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

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

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

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

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

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

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

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