إعداد Geocoding API

يصف هذا المستند الخطوات التي تحتاج إليها لبدء استخدام Geocoding API.

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

مفتاح واجهة برمجة التطبيقات رمز OAuth المميّز

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

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

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

يمكنك طلب بيانات من Google Maps API مباشرةً من خلال إرسال طلبات بيانات من واجهة برمجة التطبيقات إلى الخادم، أو يمكنك استخدام مكتبات العملاء لتبسيط الرمز البرمجي. توفّر "خرائط Google" مكتبات برامج للغات Go وJava وNode.js وPython. لمزيد من المعلومات، يُرجى الاطّلاع على مكتبات عملاء Geocoding API.

نظرة عامة على OAuth

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

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

بدلاً من ذلك، يمكنك دمج Geocoding API في تطبيق متوافق مع Android أو iOS للأجهزة الجوّالة. لمزيد من المعلومات حول استخدام OAuth وإدارة رموز الدخول لبيئات النشر المختلفة، يُرجى الاطّلاع على استخدام 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.destinations: يُستخدم فقط مع SearchDestinations لطلبات البحث عن الوجهة والوصول.
• ‫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 API في بيئة التطوير المحلية

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

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

استخدِم إجراء REST التالي لأغراض التطوير أو الاختبار فقط، وليس لأغراض الإنتاج.

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

قبل إجراء طلب REST باستخدام ADC، استخدِم واجهة سطر الأوامر (CLI) في gcloud لتقديم بيانات الاعتماد إلى ADC:

1. ثبِّت واجهة سطر الأوامر (CLI) في gcloud وافتحها. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تثبيت gcloud CLI.

2. المصادقة باستخدام واجهة سطر الأوامر (CLI) في gcloud:

   gcloud auth application-default login

3. أكمِل عملية تسجيل الدخول لحفظ بيانات الاعتماد في ملف بيانات الاعتماد المحلي الذي تستخدمه ADC.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إعداد 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. الصِق الأمر في نافذة المحطة الطرفية، ثم شغِّله.

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

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