إعداد Geocoding API

المطوّرون في المنطقة الاقتصادية الأوروبية

إذا كان عنوان الفوترة الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

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

1. الحساب والفوترة تأكَّد من استيفاء المتطلبات الأساسية.

‫2. تفعيل واجهة برمجة التطبيقات فعِّل واجهة برمجة التطبيقات في مشروعك على Google Cloud.

3. إجراء طلبك الأول ضبط مفتاح واجهة برمجة التطبيقات أو OAuth لإجراء طلب مصادقة لواجهة برمجة التطبيقات

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

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

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

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

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

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

ملاحظة:

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

راجِع مكتبات عميل Geocoding API للاطّلاع على الوثائق والأمثلة.

لمحة عن 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 غير مخصّص للاستخدام في بيئة إنتاج. استخدِم هذا الإجراء في بيئة تطوير أو اختبار فقط.

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

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

1. ثبِّت gcloud CLI وافتحه.

2. نفِّذ أمر 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/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

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

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

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

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