إعداد Geocoding API

يوضّح هذا المستند الخطوات اللازمة لبدء استخدام Geocoding API.

يتم تأمين منتجات "منصة خرائط Google" من الاستخدام غير المصرّح به من خلال اشتراط أن تتضمّن طلبات البيانات من واجهة برمجة التطبيقات إما مفتاح واجهة برمجة تطبيقات أو رمز OAuth المميز.

إنشاء رمز مميّز OAuth

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

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

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

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

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

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

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

لاستخدام OAuth مع Geocoding API، يجب منح رمز OAuth المميز النطاق الصحيح. تتيح Geocoding API النطاقات التالية:

• https://www.googleapis.com/auth/maps-platform.geocode — تُستخدَم مع جميع طرق Geocoding API.
• https://www.googleapis.com/auth/maps-platform.geocode.address — استخدِمها فقط مع GeocodeAddress للترميز الجغرافي الأمامي.
• https://www.googleapis.com/auth/maps-platform.geocode.location — استخدِمها مع GeocodeLocation فقط لعكس الترميز الجغرافي.
• https://www.googleapis.com/auth/maps-platform.geocode.place — استخدِمها فقط مع GeocodePlace لترميز المواقع الجغرافية.

يمكنك أيضًا استخدام النطاق العام https://www.googleapis.com/auth/cloud-platform لجميع طرق Geocoding API. يكون هذا النطاق مفيدًا أثناء عملية التطوير لأنّه النطاق التلقائي المستخدَم عند إنشاء الرموز المميّزة باستخدام gcloud.

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

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

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

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

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

1. تثبيت gcloud CLI وإعداده

2. نفِّذ الأمر gcloud التالي على جهازك المحلي لإنشاء ملف بيانات الاعتماد:

   gcloud auth application-default login

3. تظهر شاشة تسجيل الدخول. بعد تسجيل الدخول، يتم تخزين بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي تستخدمه ميزة "التحكّم التكيّفي في الوصول".

لمزيد من المعلومات، يُرجى الاطّلاع على إعداد ADC لبيئة تطوير محلية.

إجراء طلب REST

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

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

  gcloud auth application-default print-access-token

  يحتوي الرمز المميّز الذي تم إرجاعه على نطاق https://www.googleapis.com/auth/cloud-platform.

• مرِّر رقم تعريف أو اسم مشروعك على Google Cloud الذي تم تفعيل الفوترة فيه في العنوان X-Goog-User-Project.

يُجري المثال التالي طلبًا إلى Geocoding API باستخدام رمز OAuth مميز.

1. عدِّل الحقل PROJECT_ID لتمرير رقم تعريف مشروعك على Google Cloud.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. انقر على رمز النسخ في عينة تعليمات برمجية، ، لنسخ الأمر curl.
3. ألصِق الأمر في نافذة وحدة طرفية ونفِّذه.

الردّ هو عنصر JSON:

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

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