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

الهدف

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

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

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

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

الاختبار

غالبًا ما تريد اختبار واجهة برمجة التطبيقات 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 تفرض قيودًا على البيانات التي يمكن تخزينها في ذاكرة التخزين المؤقت.

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

الخطوة 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. كتبه المساهمون التاليون في الأصل.
المؤلفون الرئيسيون:

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