التعامل مع العناوين المعدَّلة

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

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

  • إرسال طلب إلى نقطة النهاية provideValidationFeedback
  • ضبط حقل previousResponseID

إرسال طلب provideValidationFeedback

في نهاية سلسلة من عمليات التحقّق، تنصح Google بإجراء طلب بيانات إلى واجهة برمجة التطبيقات Provide Validation Feedback API للإشارة إلى النتيجة النهائية لجميع عمليات التحقّق. يضبط الطلب حقلَين:

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

استخدِم إما الأسلوب provideValidationFeedback (REST) أو الأسلوب ProvideValidationFeedback (gRPC).

يُرسِل المثال التالي نص JSON إلى الطلب الذي يحدِّد الخاتمة:

curl -X POST -d '{
  "conclusion": "VALIDATED_VERSION_USED",
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:provideValidationFeedback?key=API_KEY"
  • يحدِّد الحقل conclusion أحد الإجراءات التالية من جانبك:
    • VALIDATED_VERSION_USED: النسخة التي تم التحقّق منها من العنوان من Address Validation API
    • ‫USER_VERSION_USED: الإصدار الأصلي الذي قدّمه المستخدم.
    • UNVALIDATED_VERSION_USED: نسخة تم إنشاؤها نتيجة طلب موجَّه إلى المستخدم، ولكن لم تتم إعادة التحقّق منها باستخدام Address Validation API
    • UNUSED: تمّت إعادة المعاملة.
راجِع استنتاج عملية التحقّق في الدليل المرجعي.
  • يحدِّد الحقل responseId نتائج التحقّق من العنوان التي تريد تقديم ملاحظات بشأنها. يجب أن تكون هذه القيمة هي نفسها قيمة responseId التي عرضتها الدعوة الأولى إلى الأسلوب validateAddress.
اطّلِع على نص الطلب في دليل المرجع الخاص بملاحظات التحقّق.

ضبط حقل previousResponseID

عند إصدار طلب متابعة إلى Address Validation API لعنوان معيّن، يجب ضبط الحقل previousResponseId.

  • بالنسبة إلى قيمة previousResponseId، استخدِم القيمة من responseId التي تعرضها واجهة برمجة التطبيقات بعد طلب التحقّق الأول.
  • استخدِم هذه القيمة نفسها لأي طلبات متابعة وكل الطلبات إلى أن تكتمل السلسلة.

يعرض مخطّط التسلسل هذا المسار المفضّل:

استخدِم معرّف الاستجابة للتحقّق من صحة عنوان.