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

الهدف

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

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

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

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

الاختبار

في كثير من الأحيان، تحتاج إلى اختبار واجهة برمجة التطبيقات Address Validation API من خلال تشغيل آلاف العناوين. قد تكون العناوين في ملف قيم مفصولة بفواصل (CSV) وتريد التحقّق من جودة العناوين.

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

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

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

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

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

نظرة متعمّقة في الجوانب الفنية

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

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

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

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

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

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

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

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

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

فهم الردّ

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

  • تكون قيمة العلامة addressComplete في العنصر Verdict هي true،
  • قيمة validationGranularity في الكائن Verdict هي PREMISE أو SUB_PREMISE
  • لم يتم تصنيف أي من AddressComponent على أنّه:
    • Inferred(Note: inferred=truecan happen when 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. يمكنك الاطّلاع عليه لبدء إنشاء تطبيقات باستخدام خدمة High Volume Address Validation بسرعة. يمكنك أيضًا الاطّلاع على المقالة حول أنماط التصميم الخاصة بكيفية استخدام المكتبة في سيناريوهات مختلفة.

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

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

محتوى إضافي للقراءة:

المساهمون

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

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