دليل التحقّق من صحة العناوين التي يتم إدخالها بأعداد كبيرة

الهدف

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

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

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

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

الاختبار

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

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

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

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

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

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

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

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

  • أنت تستدعي Address Validation API باستخدام عناوين من قاعدة بيانات العملاء (أي قاعدة بيانات تحتوي على تفاصيل العملاء)
  • يمكنك تخزين علامات الصلاحية مؤقتًا مقابل العناوين الفردية في قاعدة بياناتك.
  • Validity flags are retrieved from the Address Validation API when an individual customer logs in.

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

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

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

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

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

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

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

فهم الردّ

إذا كان الردّ من 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 بدون واجهة مستخدم

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

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

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

الخطوة 1:

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

المخطّط البياني "أ": يوضّح المخطّط البياني التالي كيف يمكن تحسين مسار نقل البيانات باستخدام منطق High Volume Address Validation.

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".

لقد كتبنا أيضًا عملية تنفيذ مرجعية لواجهة High Volume Address Validation كمكتبة برنامج مفتوح المصدر على GitHub. يمكنك الاطّلاع عليها لبدء استخدام واجهة برمجة التطبيقات High Volume Address Validation بسرعة. يمكنك أيضًا الاطّلاع على المقالة حول أنماط التصميم التي توضّح كيفية استخدام المكتبة في سيناريوهات مختلفة.

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

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

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

المساهمون

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

هنريك فالف | مهندس حلول
توماس أنغلاريت | مهندس حلول
سارثاك غانغولي | مهندس حلول