إعداد Places API (الجديدة)

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

يوضِّح هذا المستند الخطوات التي يجب اتّباعها لبدء استخدام Places API (الإصدار الجديد).

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

يساعدك هذا الإجراء في إعداد حساب على Google Cloud ومشروع على السحابة الإلكترونية مع تفعيل الفوترة. يجب أيضًا أن تكون على دراية بكيفية تحصيل الرسوم منك مقابل استخدام Places API (الإصدار الجديد).

  1. راجِع الفوترة وتكلفة الاستخدام في استخدام Places API (الجديدة) والفوترة.

  2. تأكَّد من أنّ لديك حساب على Google Cloud.

    سجِّل الدخول إلى Google Cloud Console

  3. تأكَّد من أنّ لديك مشروعًا على Google Cloud تم تفعيل الفوترة فيه.

    انتقِل إلى صفحة "الفوترة"
    1. اختَر مشروعك لفتح صفحة الفوترة.

    2. في صفحة الفوترة:

      • إذا كانت الفوترة مفعَّلة للمشروع المحدّد، وكان لديك حساب فوترة واحد فقط، ستفتح صفحة الفوترة.
      • إذا كانت لديك حسابات فوترة متعددة، اختَر الانتقال إلى حساب الفوترة المرتبط للاطّلاع على تفاصيل حساب الفوترة المرتبط بالمشروع.
      • إذا كان هناك حساب فوترة ولكنّه غير مرتبط بالمشروع، سيُطلب منك ربط حساب فوترة بالمشروع.
      • إذا لم يكن هناك حساب فوترة، أو إذا أردت إنشاء حساب فوترة جديد، اختَر إدارة حسابات الفوترة لإنشاء حساب فوترة جديد. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء حساب فوترة جديد للخدمة الذاتية على Google Cloud.

تفعيل واجهة برمجة التطبيقات

قبل استخدام Places API (الإصدار الجديد)، عليك استخدام وحدة تحكّم Google Cloud أو الأمر gcloud لتفعيلها في مشروعك على Google Cloud.

لتفعيل واجهة برمجة التطبيقات:

وحدة التحكّم

  1. افتح صفحة المنتج في Google Cloud Console:

    تفعيل Places API (الجديدة)

  2. يمكنك النقر على الزر تمكين.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "places.googleapis.com"

يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

الحصول على مفتاح واجهة برمجة تطبيقات لاستخدامه مع Places API (الجديدة)

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

مفتاح واجهة برمجة التطبيقات هو سلسلة فريدة من الأحرف الأبجدية الرقمية تربط حسابك على Cloud Billing ومشروعك على Google Cloud بالطلب الذي يرسله تطبيقك إلى واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) على "منصة خرائط Google". لإنشاء مفتاح جديد أو إضافة واجهة برمجة تطبيقات أو حزمة تطوير برامج (SDK) إلى مفتاح حالي، اتّبِع التعليمات التالية.

وحدة التحكّم

  1. انتقِل إلى صفحة منصة خرائط Google > المفاتيح وبيانات الاعتماد.

    الانتقال إلى صفحة "المفاتيح وبيانات الاعتماد"

  2. اختَر مشروعك إذا طُلب منك ذلك.

  3. نفّذ أيًا مما يلي:

    • إنشاء مفتاح جديد:

      1. انقر على إنشاء بيانات الاعتماد > مفتاح واجهة برمجة التطبيقات.
      2. في لوحة إنشاء مفتاح واجهة برمجة التطبيقات، افتح قائمة اختيار قيود واجهة برمجة التطبيقات.
      3. امسح أي واجهات برمجة تطبيقات لا يحتاجها هذا المفتاح، وتأكَّد من بقاء Places API (الجديدة) محدّدة.
      4. انقر على إنشاء. تعرض اللوحة مفتاح واجهة برمجة التطبيقات الجديد.

    • استخدام مفتاح حالي:

      1. انقر على اسم المفتاح.
      2. في قائمة اختيار قيود واجهة برمجة التطبيقات، اختَر Places API (جديدة).
      3. انقر على حفظ.

    لا يؤدي اختيار واجهة برمجة تطبيقات هنا إلى تفعيلها. تأكَّد من تفعيل Places API (الجديدة) في صفحة مكتبة واجهة برمجة التطبيقات.

  4. للاطّلاع على سلسلة المفاتيح لاحقًا، انتقِل إلى صفحة المفاتيح وبيانات الاعتماد وانقر على عرض المفتاح للمفتاح المطلوب.

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

gcloud

استبدِل PROJECT_ID برقم تعريف مشروعك في الأوامر التالية.

  • إنشاء مفتاح جديد: نفِّذ الأمر التالي، واستبدِل DISPLAY_NAME باسم المفتاح. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=places.googleapis.com

    يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

  • استخدام مفتاح حالي: نفِّذ الأمر التالي، واستبدِل KEY_ID بمعرّف المفتاح. تحتفظ العلامة --append بواجهات برمجة التطبيقات التي يسمح بها المفتاح حاليًا. وبدونها، يستبدلها الأمر.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=places.googleapis.com

    يمكنك الاطّلاع على مزيد من المعلومات حول Google Cloud SDK وتثبيت Cloud SDK والأوامر التالية:

    معرّف المفتاح ليس سلسلة المفتاح أو اسم العرض. للعثور عليه، شغِّل gcloud services api-keys list --project="PROJECT_ID". رقم التعريف هو الجزء الأخير من حقل name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

للاطّلاع على سلسلة المفاتيح، شغِّل gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

إرسال طلب بيانات من واجهة برمجة التطبيقات

أرسِل طلبًا إلى Places API (الإصدار الجديد) لعرض استجابة JSON لطلب "بحث نصي" عن السلسلة "طعام نباتي حار في سيدني، أستراليا". يجب تضمين السلسلة الأبجدية الرقمية لمفتاح واجهة برمجة التطبيقات مع كل طلب واستخدام بروتوكول HTTPS للطلبات التي تتضمّن مفتاح واجهة برمجة التطبيقات.

  1. انقر على API_KEY في الرمز أدناه لإدراج السلسلة الأبجدية الرقمية للمفتاح:

    curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'
  2. انقر على رمز النسخ في عيّنة التعليمات البرمجية، انقر على رمز النسخ.، لنسخ الأمر curl.
  3. الصِق الأمر في نافذة الوحدة الطرفية ونفِّذه.

الردّ هو عنصر JSON بالصيغة التالية:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

تطبيق قيود على مفتاح واجهة برمجة التطبيقات

تنصح Google بشدة بفرض قيود على مفاتيح واجهة برمجة التطبيقات من خلال حصر استخدامها على واجهات برمجة التطبيقات والتطبيقات التي تحتاج إليها فقط. يؤدي فرض قيود على مفاتيح واجهة برمجة التطبيقات إلى تعزيز أمان تطبيقك من خلال حمايته من الطلبات غير المبرَّرة. تتيح مفاتيح واجهة برمجة التطبيقات نوعَين من القيود:

  • تحدّد القيود المفروضة على واجهة برمجة التطبيقات حِزم SDK وواجهات برمجة التطبيقات التي يمكن طلبها باستخدام مفتاح واجهة برمجة التطبيقات. تتطلّب وحدة التحكّم وgcloud CLI فرض قيد واحد على الأقل على واجهة برمجة التطبيقات عند إنشاء مفتاح.
  • تحدّد قيود التطبيقات المواقع الإلكترونية أو عناوين IP أو التطبيقات التي يمكنها استخدام مفتاح واجهة برمجة التطبيقات.

لمزيد من المعلومات حول تطبيق القيود، يُرجى الاطّلاع على مقالة فرض قيود على مفاتيح واجهة برمجة التطبيقات.

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

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

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

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

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

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

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

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

نطاقات OAuth

لاستخدام OAuth مع Places API (الإصدار الجديد)، يجب منح رمز OAuth المميّز النطاق التالي:

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

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

إذا لم تكن لديك بيئة تنشئ رموزًا مميّزة وأردت تجربة Places 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.

لطلب Places API (الإصدار الجديد) باستخدام رمز OAuth المميّز، أكمِل الخطوات التالية:

  1. في عينة التعليمات البرمجية التالية، استبدِل PROJECT_ID برقم تعريف مشروعك على Google Cloud:

    curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress" \
"https://places.googleapis.com/v1/places:searchText"

  2. لنسخ الأمر curl، انقر على نسخ في عينة التعليمات البرمجية.

  3. الصِق الأمر في نافذة المحطة الطرفية، ثم شغِّله.

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

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

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

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

الخطوات التالية

بعد تفعيل Places API (جديدة) وضبط مفتاح واجهة برمجة التطبيقات، يمكنك الاطّلاع على مقالة لمحة عن Places API (جديدة) لمعرفة المزيد عن كيفية استخدام Places API (جديدة).