تأكيد العنوان - أمثلة

يوضِّح هذا المستند عددًا من السيناريوهات الفعلية التي توفّر فيها "واجهة برمجة التطبيقات للتحقق من صحة العنوان" إشارات استجابة للعناوين التي تتطلب سلوكًا مؤكَّدًا من نظامك. يمكنك الاطّلاع على نظرة عامة على سير العمل في مقالة إنشاء منطق التحقّق للحصول على السياق.

أمثلة شائعة: التأكيد

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

تم إدخال العنوان	منطقة
المبنى D, 451 7th Avenue South, سياتل، واشنطن 98033	الولايات المتحدة

القرار بشأن البيانات التي تم استبدالها

يؤكد المثال أدناه على الإشارات المهمة من الرد.

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true
}

تشير السمة PREMISE_PROXIMITY إلى تقريب من العنوان على مستوى المبنى، ولكنها ليست مفصلة عن SUB_PREMISE، وهي الدقة المتوفرة في الإدخال. يحتوي الردّ أيضًا على مكوّنات غير مؤكّدة تم استبدالها ومكوّنات أخرى، لذا فإنّ الجمع بينها يضع في هذه الفئة ضمن الفئة confirm (تأكيد).

يكشف طلب البحث عن مكونات العنوان عن النواحي التالية المثيرة للجدل:

{
  "componentName": {
    "text": "451",
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
  "componentName": {
    "text": "98104",
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "replaced": true
}
...
{
  "componentName": {
    "text": "Building D",
    "language_code": "en"
  },
  "componentType": "subpremise",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......

    "unconfirmedComponentTypes": [
      "street_number",
      "subpremise"
    ]

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

أمثلة على الحالات الحدّية: تأكيد

توضح الأمثلة التالية أنواع الحالات الهامشية التالية:

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

استنتاجات بسيطة تم تأكيدها

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

• المدينة
• الحالة
• رمز بريدي
• البلد

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

تم إدخال العنوان	منطقة
1402 Allen St, MA 01118	الولايات المتحدة

الحكم على المدينة المفقودة

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "hasInferredComponents": true
}

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

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

{
  "componentName": {
    "text": "Springfield",
    "languageCode": "en"
  },
  "componentType": "locality",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
},
{
  "componentName": {
    "text": "1806"
  },
  "componentType": "postal_code_suffix",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

لم يتم تأكيد عنصر العنوان غير المتوقع

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

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

تم إدخال العنوان	منطقة
1 Rue Grenache, lacaritat 2, 34630 San-Thibéry	فرنسا

لم يتم تأكيد قرار مكون العنوان غير المتوقع

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "unconfirmedComponents": true
}

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

"formattedAddress": "1 Rue Grenache, 34630 Saint-Thibéry, France",

يُظهر فحص للمكونات التي لم يتم تأكيدها أنّ واجهة برمجة التطبيقات أزالت lacaritat 2 من العنوان المعروض:

{
  "componentName": {
    "text": "la caritat 2",
    "languageCode": "fr"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

عنصر عنوان غير متوقع تم تأكيده

يوضّح هذا المثال إدراج مقاطعة من المملكة المتحدة في العنوان المقدّم، وهو ممارسة شائعة. ومع ذلك، لا تفرض هيئة البريد في المملكة المتحدة هذا الشرط ويتم تجاهله بشكل أساسي. يمكنك الاطّلاع على postoffice.co.uk وكيفية توجيه الرسائل الإلكترونية في المملكة المتحدة والدولي.

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

تم إدخال العنوان	منطقة
33 Dunalley St, Cheltenham, Gloucestershire, GL50 4AP	المملكة المتحدة

بيان مكون عنوان غير متوقع تم تأكيده

{
   "inputGranularity": "PREMISE",
   "validationGranularity": "PREMISE",
   "geocodeGranularity": "PREMISE"
}

في هذه الحالة، يتم تقييم address_complete إلى false ويكشف تحليل مكوّن العنوان علامة غير متوقعة.

{
  "componentName": {
    "text": "Gloucestershire",
    "languageCode": "en"
  },
  "componentType": "administrative_area_level_2",
  "confirmationLevel": "CONFIRMED",
  "unexpected": true
}

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