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

الهدف

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

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

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

سنشرح الآن حالات الاستخدام التي تكون فيها ميزة التحقّق من صحة العناوين بكميات كبيرة مفيدة.

الاختبار

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

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

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

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

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

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

نظرة متعمّقة فنية

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

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

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

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

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

  • البيانات من عنصر AddressComponent object
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

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

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

بموافقة المستخدم، يمكنك تخزين 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" من البيانات التي يمكن تخزينها مؤقتًا.

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

الخطوة 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. يمكنك الاطّلاع عليها لبدء الإنشاء باستخدام ميزة "التحقّق من صحة العناوين بكميات كبيرة" بسرعة. يمكنك أيضًا الاطّلاع على المقالة حول أنماط تصميم كيفية استخدام المكتبة في سيناريوهات مختلفة.

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

نزِّل المستند التقني تحسين عملية الدفع والتسليم والعمليات باستخدام عناوين موثوقة واطّلِع على الندوة الإلكترونية تحسين عملية الدفع والتسليم والعمليات باستخدام Address Validation .

مقالات نقترح قراءتها:

المساهمون

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

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