استخدام واجهة برمجة تطبيقات التحقق من العنوان لمعالجة العناوين بحجم كبير

الهدف

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

Address Validation API هو منتج من Google Maps Platform يمكنك استخدامه للتحقّق من صحة عنوان. ومع ذلك، لا تتم معالجة سوى عنوان واحد في كل مرة. في هذا المستند، سننظر في كيفية استخدام ميزة "التحقّق من العناوين ذات الحجم الكبير" في سيناريوهات مختلفة، بدءًا من اختبار واجهة برمجة التطبيقات ووصولاً إلى التحقّق من العناوين لمرة واحدة وبشكل متكرّر.

حالات الاستخدام

سنوضّح الآن حالات الاستخدام التي يكون فيها التحقّق من العناوين ذات الحجم الكبير مفيداً.

الاختبار

غالبًا ما تريد اختبار واجهة برمجة التطبيقات Address Validation API من خلال تشغيل آلاف العناوين. قد تكون لديك العناوين في ملف "قيم مفصولة بفواصل" وتريد التحقّق من جودة العناوين.

التحقّق من صحة العناوين لمرة واحدة

أثناء إعداد واجهة برمجة التطبيقات Address Validation API، عليك التحقّق من صحة قاعدة بيانات العناوين الحالية مقارنةً بقاعدة بيانات المستخدمين.

التحقّق المتكرّر من صحة العناوين

تتطلّب بعض السيناريوهات التحقّق من صحة العناوين بشكل متكرّر:

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

نظرة تفصيلية على الجوانب الفنية

لأغراض هذا المستند، نفترض ما يلي:

  • يتم استدعاء Address Validation API باستخدام عناوين من قاعدة بيانات العميل (أي قاعدة بيانات تحتوي على تفاصيل العميل).
  • يمكنك تخزين علامات الصحة في ذاكرة التخزين المؤقت للعناوين الفردية في قاعدة بياناتك.
  • يتم استرداد علامات الصحة من Address Validation API عندما سجّل أحد العميلِين الفرديين الدخول.

ذاكرة التخزين المؤقت لاستخدامها في مرحلة الإنتاج

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

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

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

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

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

فهم الاستجابة

إذا كان ردّ Address Validation API يتضمّن العلامات التالية، يمكنك التأكّد من أنّ عنوان الإدخال بجودة قابلة للتسليم:

  • علامة addressComplete في Verdict العنصر هي true،
  • القيمة validationGranularity في Verdict الكائن هي PREMISE أو SUB_PREMISE
  • لا يتم وضع علامة على أيّ من AddressComponent على أنّه:
    • Inferred(ملاحظة: inferred=trueيمكن أن يحدث ذلك عند addressComplete=true)
    • spellCorrected
    • replaced
    • unexpected، و
  • confirmationLevel: تم ضبط مستوى التأكيد على AddressComponent علىCONFIRMEDأوUNCONFIRMED_BUT_PLAUSIBLE

إذا لم يتضمّن ردّ واجهة برمجة التطبيقات العلامات أعلاه، من المرجّح أن يكون عنوان الإدخال ذا جودة منخفضة، ويمكنك تخزين الإشارات في ذاكرة التخزين المؤقت في قاعدة بياناتك للإشارة إلى ذلك. تشير الإشارات المخزّنة مؤقتًا إلى أنّ العنوان ككلّ منخفض الجودة، في حين تشير الإشارات الأكثر تفصيلاً، مثل "تم تصحيح الأخطاء الإملائية"، إلى النوع المحدّد من مشكلة جودة العنوان. عند تفاعل العميل التالي مع عنوان تم وضع علامة عليه بأنّه منخفض الجودة، يمكنك استدعاء Address Validation API باستخدام العنوان الحالي. ستُرجع واجهة برمجة التطبيقات Address Validation API العنوان الذي تم تصحيحه والذي يمكنك عرضه باستخدام طلب واجهة مستخدم. بعد قبول العميل للعنوان المنسَّق، يمكنك تخزين ما يلي من الردّ في ذاكرة التخزين المؤقت:

  • formattedAddress
  • postalAddress
  • addressComponent componentNamesأو
  • UspsData standardizedAddress

تنفيذ عملية تحقّق من العنوان بدون عرض

استنادًا إلى المناقشة أعلاه:

  • غالبًا ما يكون من الضروري تخزين بعض أجزاء الاستجابة من واجهة برمجة التطبيقات Address Validation API في ذاكرة التخزين المؤقت لأسباب تتعلّق بالنشاط التجاري.
  • ومع ذلك، تفرض بنود الخدمة في Google Maps Platform قيودًا على البيانات التي يمكن تخزينها مؤقتًا.

في القسم التالي، سنناقش عملية من خطوتَين حول كيفية الامتثال لبنود الخدمة وتنفيذ عملية التحقّق من العناوين ذات الحجم الكبير.

الخطوة 1:

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

المخطّط البياني (أ): يوضّح المخطّط البياني التالي كيفية تحسين مسار بيانات باستخدام منطق التحقّق من العناوين ذات الحجم الكبير.

alt_text

وفقًا لبنود الخدمة، يمكنك تخزين البيانات التالية مؤقتًا من addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

وبالتالي، خلال هذه الخطوة من التنفيذ، سنخزّن في ذاكرة التخزين المؤقت الحقلَين المذكورَين أعلاه مقارنةً بـ UserID.

لمزيد من المعلومات، اطّلِع على تفاصيل حول بنية البيانات الفعلية.

الخطوة 2:

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

المخطّط "ب": يوضّح هذا المخطّط كيفية دمج تدفق موافقة العميل بالكامل:

alt_text

  1. عندما يسجّل المستخدم الدخول، تحقّق أولاً ممّا إذا كنت قد خزّنت مؤقتًا أي علامات تحقّق في نظامك.
  2. في حال توفّر إشعارات، يجب أن تقدّم للمستخدم واجهة مستخدم لتصحيح عنوانه وتعديله.
  3. يمكنك استدعاء Address Validation API مرة أخرى باستخدام العنوان المعدَّل أو المحفوظ في ذاكرة التخزين المؤقت وعرض العنوان المصحَّح على المستخدم لتأكيده.
  4. إذا كان العنوان ذا جودة عالية، ستعرض واجهة برمجة التطبيقات Address Validation API formattedAddress.
  5. يمكنك إما عرض هذا العنوان على المستخدم إذا تم إجراء تعديلات عليه، أو قبوله بدون إشعار إذا لم تكن هناك أي تعديلات.
  6. بعد قبول المستخدم، يمكنك تخزين formattedAddress في ذاكرة التخزين المؤقت في قاعدة البيانات.

الخاتمة

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

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

الخطوات التالية

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

مراجع إضافية مقترَحة:

المساهمون

تُعدّ هذه المقالة من إعداد Google. كتب المساهمون التاليون هذه المقالة في الأصل.
المؤلفون الرئيسيون:

Henrik Valve | مهندس حلول
Thomas Anglaret | مهندس حلول
Sarthak Ganguly | مهندس حلول