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

الهدف

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

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

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

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

الاختبار

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

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

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

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

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

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

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

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

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

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

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

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

  • البيانات الواردة من عنصر القرار

    • inputGranularity
    • validationGranularity
    • geocodeGranularity
    • addressComplete
    • hasUnconfirmedComponents
    • hasInferredComponents
    • hasReplacedComponents

  • البيانات من العنصر AddressComponent

    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

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

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

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

فهم الردّ

إذا كانت استجابة واجهة برمجة التطبيقات للتحقق من صحة العنوان تحتوي على العلامات التالية، يمكنك أن تثق في أن عنوان الإدخال ذو جودة قابلة للمُخرَج النهائي:

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

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

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

تنفيذ عملية التحقّق من صحة العنوان بلا واجهة مستخدم رسومية

بناءً على المناقشة أعلاه:

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

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

الخطوة 1:

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

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

alt_text

  • وفقًا لبنود الخدمة، يمكنك تخزين addressComplete,validationGranularity and validationFlags مؤقتًا عند التحقق من صحة العناوين بطريقة بلا واجهة مستخدم رسومية .

  • يمكنك تخزين addressComplete,validationGranularity and validationFlags, PlaceID مؤقتًا مقابل UserID معيّن في قاعدة بيانات العملاء.

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

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

الخطوة 2:

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

الرسم البياني ب: يوضّح هذا المخطّط البياني الشكل الذي يمكن أن يظهر به الدمج التام بين الأطراف لتدفق موافقة المستخدِم:

alt_text

  1. بعد أن يسجِّل المستخدم الدخول، عليك أولاً التحقّق مما إذا كنت قد خزّنت مؤقتًا أي علامات تحقُّق في نظامك، مثل:

    • addressComplete صحيح
    • validationGranularity لا تعني PREMISE أو SUB_PREMISE.
    • validationFlags يتم الآن inferred,spellCorrected,replaced,unexpected.
      • إذا لم يتم الإبلاغ عن أي أخطاء، تكون هناك ثقة كبيرة في أنّ العنوان المخزّن الحالي المخزَّن بجودة جيدة، وأنّه يمكن استخدامه.

  2. في حال ظهور علامات، يجب توفير واجهة مستخدم للمستخدم لتصحيح عنوانه أو تعديله.

  3. يمكنك استدعاء واجهة برمجة التطبيقات التحقّق من صحة العنوان مرة أخرى باستخدام العنوان المعدَّل أو المخزَّن مؤقتًا وتقديم العنوان المصحَّح للمستخدم لتأكيده.

  4. إذا كان العنوان ذا جودة جيدة، تعرض واجهة برمجة تطبيقات التحقّق من صحة العنوان formattedAddress.

  5. ويمكنك تقديم هذا العنوان إلى المستخدم إذا كان قد تم إجراء أي تصحيحات، أو القبول بدون تنبيه إذا لم تكن هناك أي تصحيحات.

  6. بعد قبول المستخدم، يمكنك تخزين formattedAddress مؤقتًا في قاعدة البيانات.

تنفيذ رمز زائف الخطوة 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

الخلاصة

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

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

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

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

اقترحت مزيدًا من القراءة:

المساهمون

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

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