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

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

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

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

إرسال طلب provideValidationFeedback

في نهاية سلسلة من عمليات التحقق، تنصح Google بإجراء طلب إلى Provideation 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: إصدار نتيجة طلب إلى المستخدم، ولكن لم تتم إعادة التحقق منه باستخدام واجهة برمجة تطبيقات التحقق من صحة العنوان.
  • UNUSED: تم إلغاء المعاملة.

• يحدِّد الحقل responseId نتائج التحقّق من العنوان التي تريد تقديم ملاحظات بشأنها. يجب أن تكون هذه القيمة هي نفسها قيمة responseId التي عرضتها الدعوة الأولى إلى الأسلوب validateAddress.

ضبط الحقل previousResponseID

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

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

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