يصف هذا المستند عملية لإنشاء نظام للتحقق من العنوان للتعامل مع مجموعة متنوعة من الردود من واجهة برمجة تطبيقات التحقق من العناوين. ويتناول هذا الدليل طريقة إنشاء منطق لاستخدام الاستجابة بشكل صحيح، والتحقيق في الإشارات الأخرى من واجهة برمجة التطبيقات، والحالات التي تتطلّب في ذلك طلب المزيد من المعلومات من عملائك، وكيفية إجراء ذلك.
وبشكل عام، تحدّد استجابة واجهة برمجة التطبيقات الطرق التالية التي يجب أن يعالج بها نظامك أحد العناوين:
- إصلاح: العنوان منخفض الجودة. يجب إرسال طلب للحصول على مزيد من المعلومات.
- تأكيد: العنوان عالي الجودة، ولكن يتضمّن تغييرات من العنوان الذي تم إدخاله. قد يُطلب منك التأكيد.
- قبول: العنوان عالي الجودة ويمكنك قبول العنوان المقدَّم.
الغرض الرئيسي
يساعدك هذا المستند في تعديل النظام لتحليل استجابة واجهة برمجة التطبيقات على أفضل نحو وتحديد الإجراءات التالية التي يجب اتخاذها بشأن العناوين المتوفرة. يوضح الكود الزائف التالي التدفق المحتمل.
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وهي ليست هي الإشارات الوحيدة التي يجب التحقق منها، ولكنها توفّر مؤشرًا أوليًا لجودة العنوان. يتوافق كل نوع سلوك مع قسم في هذا المستند يصف المزيد من الإشارات التي قد تحتاج أيضًا إلى التحقق منها.
| سلوك النظام | |||
|---|---|---|---|
| تصحيح العنوان |
يشير الردّ من
|
||
| تأكيد العنوان |
ويشير الردّ من
|
||
| قبول العنوان |
تشير استجابة واجهة برمجة التطبيقات للتحقق من صحة العنوان إلى عنوان ممتاز.
|
||
إرشادات التنفيذ
عند تصميم طريقة استجابة نظامك للإشارات الواردة من واجهة برمجة تطبيقات التحقق من صحة العناوين، يمكن أن تساعدك الاقتراحات التالية في إنشاء نموذج استجابة أكثر فعالية. مع ذلك، هذه الاقتراحات ليست سوى اقتراحات، لذا تذكَّر أنّ طريقة التنفيذ يجب أن تناسب نموذج أعمالك.
| الإرشادات | التفاصيل | |
|---|---|---|
| مستوى المخاطر |
يجب أن يأخذ في الاعتبار مستوى التساهل مع موقفك عند تحقيق التوازن بين المطالبة بإجراء تصحيحات وقبول العنوان كما تم إدخاله. |
تعرض واجهة برمجة تطبيقات التحقق من صحة العناوين مجموعة متنوعة من الإشارات التي يمكنك دمجها مع مستوى المخاطر لتحسين عملية التحقق. على سبيل المثال، إذا كان العنوان يتضمّن رقم شارع غير مؤكّد، لا يزال بإمكانك قبوله. من ناحية أخرى، إذا كانت عمليات نشاطك التجاري تتطلب دقة أكبر في العنوان، يمكنك طلب ذلك من المستخدم. للاطّلاع على مثال يمكن أن يندرج ضمن أي من الفئتين، يمكنك الاطّلاع على رقم الشارع الذي لا يتم تأكيده في الولايات المتحدة في مقالة قبول العنوان - أمثلة. |
| قبول العناوين |
من الممارسات الجيدة السماح لنظامك بقبول الإدخال الأصلي إذا لم يردّ العميل على الطلبات. |
في هذه الحالات، قد يدخل العميل عنوانًا غير متوفر في النظام، مثل عنوان البناء الجديد. |
| تقديم ملاحظات وآراء |
عند إعادة إصدار طلب تأكيد صحة العنوان، يمكنك أيضًا إرسال طلب إلى نقطة النهاية |
يتيح ذلك لمحرّك بحث Google معرفة الطريقة التي تعاملت بها في النهاية مع الردّ النهائي. يُرجى الاطِّلاع على التعامل مع العناوين المعدّلة. |
تصحيح عنوان
إصلاح عنوان عندما تشير النتائج بوضوح إلى أن العنوان غير قابل للتسليم. يمكن أن يطلب نظامك بعد ذلك من العميل تقديم المعلومات الضرورية، وبعد ذلك يمكنك إعادة إصدار سير العمل للحصول على عنوان التسليم.
إصلاح الإشارات
توفّر واجهة برمجة تطبيقات التحقق من صحة العنوان عددًا من الإشارات لإعلامك بما إذا كان يجب إصلاح العنوان.
1- دقة التحقق من الصحة والمكونات غير المتوفرة
توفِّر هاتان الإشارتان أفضل إشارة إلى العنوان الذي يتضمّن المشكلة:
- عندما يكون الحقل
validationGranularityهوOTHER، يجب أن يتحقّق نظامك من إشارات مكوّنات العنوان لمعرفة المزيد من المعلومات حول مكان حدوث الخطأ وكيفية إصلاحه. - عندما يعرض كائن
addressالذي تمت معالجته بعد ذلك الحقلmissingComponentTypes، من المفترض أن يتحقّق النظام من ذلك المكوّن. تعرض المكونات المفقودة أيضًا عنوانًا غير مكتمل وغير قابل للتسليم.
2. الإشارات الأخرى
توفر واجهة برمجة تطبيقات التحقق من صحة العناوين أيضًا إشارات أخرى للمساعدة في تشخيص مشاكل معينة:
| المكوّنات المريبة | عندما يكون تعداد مستوى التأكيد للمكوّن هو UNCOMFIRMED_AND_SUSPICIOUS، من المرجّح أن يكون هذا المكوِّن غير صحيح.
|
|---|---|
| المكوِّن الذي لم يتم حله | unresolvedToken هو جزء من الإدخال الذي لم يتم التعرّف عليه كجزء صالح من العنوان. |
3- إشارات العناوين في الولايات المتحدة
تقدم بعض الحقول التي تنطبق على عناوين الولايات المتحدة فقط إشارة مفيدة إلى أن العنوان ليس قابلاً للتسليم ويجب إصلاحه. بالنسبة إلى العنوان الذي يتطلب حلّاً، من المفترض أن يظهر لك ما يلي:
dpvConfirmation
|
حقل N أو D أو حقل فارغ.
|
|---|
للحصول على تفاصيل عن dpvConfirmation، يُرجى الاطّلاع على التعامل مع العناوين في الولايات المتحدة.
تأكيد عنوان
أنت تؤكد عنوانًا عندما يشير البيان إلى أن واجهة برمجة تطبيقات التحقق من صحة العنوان إما تم استنتاجها أو أجريت تغييرات على عنوانها لإنتاج عنوان تم التحقق منه. في هذه الحالات، يكون لديك عنوان للتسليم، ولكنك تفضل ثقة أكبر في أن العنوان الناتج هو العنوان الذي قصده العميل.
لتزويد العميل بالطلبات الصحيحة، سيحدّد منطقك المكوّنات التي تم وضع علامة عليها من خلال الخدمة لتحديد الإجراء أو وضع علامة على واجهة برمجة التطبيقات
التي تم تطبيقها على المكوِّن، مثل inferred أو replaced أو spellCorrected.
يُرجى الاطّلاع على AddressComponent في المرجع.
تأكيد الإشارات
توفّر واجهة برمجة تطبيقات التحقق من صحة العنوان عددًا من الإشارات لإعلامك بما إذا كان ينبغي تأكيد العنوان.
1- دقة التحقق من الصحة
من المقبول استخدام validationGranularity بقيمة ROUTE أو أفضل، ولكنّ
"PREMISE" أو "SUBMISE" يشيران إلى إمكانية تسليم المحتوى بشكل أقوى.
2. الإشارات الأخرى
عند اتخاذ قرار بتأكيد إدخال العنوان مع العميل، يوفر البيان أيضًا ما يلي لتحديد المكونات التي يجب التحقق منها:
| البيانات المستنتَجة | عندما يكون الحقل hasInferredComponents true، يعني ذلك أنّ واجهة برمجة التطبيقات ملأت المعلومات التي استخلصتها من مكونات العنوان الأخرى.
|
|---|---|
| البيانات التي تم استبدالها | عندما يكون الحقل hasReplacedComponents true،
استبدلت واجهة برمجة التطبيقات البيانات التي تم إدخالها بالبيانات التي تعتبرها صالحة للعنوان.
|
3- إشارات العناوين في الولايات المتحدة
تشير بعض الحقول التي تنطبق على عناوين الولايات المتحدة فقط إلى أن منطقك يجب أن يؤكد التفاصيل مع العميل. ينطبق أي مما يلي:
dpvConfirmation
|
S
لمعرفة تفاصيل عن |
|---|---|
| الردّ على العنوان | يحتوي على الحقل missingComponentType بقيمة
subpremise.
|
قبول عنوان
أنت تقبل عنوانًا عندما يوفر القرار درجة عالية من الثقة في أنّ العنوان قابل للتسليم ويمكن استخدامه بدون تفاعل إضافي مع العملاء في عملية استلام الطلب.
قبول الإشارات
توفّر واجهة برمجة تطبيقات التحقق من صحة العنوان عددًا من الإشارات لإعلامك بما إذا كان ينبغي تأكيد العنوان.
1- دقة التحقق من الصحة
من المقبول استخدام validationGranularity بقيمة PREMISE أو أفضل، ولكن في بعض
الحالات، لا تزال ROUTE تشير إلى عنوان تسليم.
2. الإشارات الأخرى
يجب أيضًا أن يتضمن قرار الحصول على عنوان عالي الجودة ما يلي:
- ما مِن بيانات بديلة. وهي في هذه الحالة
hasReplacedComponents: FALSE. - ما مِن مكوّنات مستنتَجة. وهي في هذه الحالة
hasInferredComponents: FALSE.
3- إشارات العناوين في الولايات المتحدة
تشير بعض الحقول التي تنطبق على العناوين في الولايات المتحدة فقط إلى عنوان عالي الجودة يمكن تسليمه إليه. للحصول على عنوان مقبول في الولايات المتحدة، من المفترض أن يظهر ما يلي:
dpvConfirmation
|
Y
لمعرفة تفاصيل عن |
|---|