استخدام OAuth

تتيح واجهة برمجة تطبيقات التحقّق من صحة العناوين استخدام بروتوكول OAuth 2.0 للمصادقة. تتيح Google استخدام سيناريوهات OAuth 2.0 الشائعة، مثل سيناريوهات خادم الويب.

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

قبل البدء

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

لمحة عن بروتوكول OAuth

هناك العديد من الطرق لإنشاء رموز الدخول وإدارتها باستخدام بروتوكول OAuth استنادًا إلى بيئة النشر.

على سبيل المثال، يدعم نظام Google OAuth 2.0 التفاعلات من خادم إلى خادم، مثل تلك التفاعلات بين التطبيق وخدمة Google. بالنسبة إلى هذا السيناريو، أنت بحاجة إلى حساب خدمة، وهو حساب ينتمي إلى تطبيقك بدلاً من حساب مستخدم نهائي فردي. يستدعي تطبيقك واجهات برمجة التطبيقات Google APIs بالنيابة عن حساب الخدمة، لذا لا يشارك المستخدمون بشكل مباشر في ذلك. لمزيد من المعلومات حول طرق المصادقة، راجِع المصادقة في Google.

وبدلاً من ذلك، يمكنك استخدام واجهة برمجة تطبيقات التحقّق من العنوان كجزء من تطبيق للأجهزة الجوّالة على نظام التشغيل Android أو iOS. للحصول على معلومات عامة عن استخدام OAuth مع واجهة برمجة تطبيقات التحقّق من صحة العناوين، بما في ذلك معلومات عن إدارة رموز الدخول لبيئات نشر مختلفة، يُرجى الاطّلاع على استخدام OAuth 2.0 للوصول إلى Google APIs.

لمحة عن نطاقات OAuth

لاستخدام OAuth مع واجهة برمجة تطبيقات التحقّق من صحة العنوان، يجب تخصيص النطاق لرمز OAuth المميّز:

  • https://www.googleapis.com/auth/cloud-platform

مثال: تجربة طلبات البيانات من واجهة برمجة التطبيقات REST في بيئة التطوير المحلية

إذا كنت ترغب في تجربة واجهة برمجة التطبيقات للتحقق من صحة العنوان باستخدام رمز OAuth مميز، ولكن ليس لديك بيئة يتم إعدادها لإنشاء الرموز المميزة، يمكنك استخدام الإجراء الوارد في هذا القسم لإجراء الاتصال.

يوضِّح هذا المثال كيفية استخدام رمز OAuth المميز المقدَّم من بيانات الاعتماد التلقائية للتطبيق (ADC) لإجراء الطلب. وللحصول على معلومات عن استخدام ADC لطلب بيانات Google APIs باستخدام مكتبات العملاء، يُرجى الاطّلاع على المقالة المصادقة باستخدام مكتبات العملاء.

المتطلبات الأساسية

قبل أن تتمكّن من تقديم طلب REST باستخدام ADC، استخدِم واجهة سطر الأوامر في Google Cloud لتقديم بيانات الاعتماد إلى ADC:

  1. أنشئ مشروعًا وفعِّل الفوترة، إذا لم يسبق لك ذلك، من خلال اتّباع الخطوات الواردة في الإعداد في Google Cloud Console.
  2. تثبيت gcloud CLI وإعداده
  3. شغِّل أمر gcloud التالي على جهازك المحلي لإنشاء ملف بيانات الاعتماد:

    gcloud auth application-default login
  4. ستظهر لك شاشة لتسجيل الدخول. بعد تسجيل الدخول، يتم تخزين بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي يستخدمه ADC.

لمزيد من المعلومات، يُرجى الاطّلاع على قسم بيئة التطوير المحلي في مستندات توفير بيانات الاعتماد الخاصة ببيانات الاعتماد التلقائية للتطبيق.

تقديم طلب REST

في هذا المثال، تمرر عنواني طلب:

  • أدخِل رمز OAuth المميز في عنوان Authorization باستخدام الأمر التالي لإنشاء الرمز:

    gcloud auth application-default print-access-token

    يشمل الرمز المميّز المعروض نطاق https://www.googleapis.com/auth/cloud-platform..

  • أدخِل رقم تعريف أو اسم مشروعك على Google Cloud الذي تم تفعيل الفوترة فيه في العنوان X-Goog-User-Project. لمزيد من المعلومات، يُرجى الاطّلاع على الإعداد في Cloud Console.

في المثال التالي، يتم الاتصال بواجهة برمجة تطبيقات التحقّق من صحة العناوين باستخدام رمز OAuth مميز:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://addressvalidation.googleapis.com/v1:validateAddress"

تحديد المشاكل وحلّها

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