تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

تم إدخال العنوان	المنطقة
Building D, 451 7th Avenue South, Seattle, WA 98033	الولايات المتحدة

نتيجة البيانات المستبدَلة

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

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

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

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

{
  "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"
    ]

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

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

توضّح الأمثلة التالية أنواع حالات الاستخدام الحدّية:

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

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

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

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

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

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

نتيجة عدم توفّر المدينة

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

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

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

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

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

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

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

تم إدخال العنوان	المنطقة
59 Cherrydown Avenue, Chingford, London E4 8DT	المملكة المتحدة

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

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

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

"formattedAddress": "59 Cherrydown Avenue, London E4 8DT, UK",

يُظهر البحث عن المكوّنات غير المؤكَّدة أنّ واجهة برمجة التطبيقات أزالت Chingford من العنوان الذي تم عرضه:

{
  "componentName": {
    "text": "Chingford",
    "languageCode": "en"
  },
  "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",
   "possibleNextAction": "ACCEPT"
}

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

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

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