إعداد Places Aggregate API

يوضّح هذا المستند الخطوات التي يجب اتّباعها لبدء استخدام Places Aggregate API.

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

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

1. راجِع الفوترة وتكلفة الاستخدام في استخدام واجهة برمجة التطبيقات Places Aggregate API وفوترتها.

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

   سجِّل الدخول إلى Google Cloud Console
   ملاحظة: إذا كنت مستخدمًا جديدًا وليس لديك حساب على Google Cloud، ما يعني أنّه لا يمكنك تسجيل الدخول إلى وحدة التحكّم، يُرجى الاطّلاع على بدء استخدام "منصة خرائط Google".

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

   انتقِل إلى صفحة "الفوترة"
   ملاحظة: إذا كنت مستخدمًا جديدًا وليس لديك مشروع على Google Cloud، يُرجى الاطّلاع على بدء استخدام "منصة خرائط Google".
1. اختَر مشروعك لفتح صفحة الفوترة.

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

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

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

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

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

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

وحدة التحكّم

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

   تفعيل Places Aggregate API

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

   ملاحظة: إذا كانت واجهة برمجة التطبيقات مفعَّلة، سيظهر لك الزر إدارة بدلاً من تفعيل.

gcloud

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

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

• gcloud services enable
• gcloud services disable

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

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

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

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

وحدة التحكّم

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

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

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

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

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

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

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

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

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

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

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

gcloud

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

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

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

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

  • gcloud services api-keys create

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

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

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

  • gcloud services api-keys update
  • gcloud services api-keys list

  معرّف المفتاح ليس سلسلة المفتاح أو اسم العرض. للعثور عليه، شغِّل 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".

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

يعرض هذا المثال طلبًا لعرض عدد المطاعم في سان فرانسيسكو ذات الأسعار المعتدلة.

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

   curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
   --header 'X-Goog-Api-Key: API_KEY' \
   --header 'Content-Type: application/json' \
   --data '{
      "insights":[
         "INSIGHT_COUNT"
      ],
      "filter":{
         "locationFilter":{
            "region":{
               "place":"places/ChIJIQBpAG2ahYAR_6128GcTUEo"
            }
         },
         "typeFilter":{
            "includedTypes":[
               "restaurant"
            ]
         },
         "priceLevels":[
            "PRICE_LEVEL_INEXPENSIVE"
         ]
      }
   }'
   

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

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

{
  "count": "1025"
}

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

تنبيه: يمكن استخدام مفتاح واجهة برمجة تطبيقات غير مقيّد لإرسال طلب إلى أي خدمة في "منصة خرائط Google"، بما في ذلك Places Aggregate API. أنت مسؤول ماليًا عن الرسوم الناتجة عن إساءة استخدام مفاتيح واجهة برمجة التطبيقات غير المقيَّدة.

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

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

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

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

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

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

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

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

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

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

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

نطاقات OAuth

لاستخدام OAuth مع Places Aggregate API، عليك منح رمز OAuth المميّز النطاق التالي:

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

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

إذا لم تكن لديك بيئة تنشئ رموزًا مميّزة وأردت تجربة Places Aggregate 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 Aggregate API باستخدام رمز OAuth المميّز، أكمِل الخطوات التالية:

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

   يعرض هذا المثال طلبًا لعرض عدد المطاعم في سان فرانسيسكو ذات الأسعار المعتدلة:

   curl -X POST 'https://areainsights.googleapis.com/v1:computeInsights' \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   --data '{
   "insights":[
     "INSIGHT_COUNT"
   ],
   "filter":{
     "location_filter":{
        "region":{
           "place":"places/ChIJIQBpAG2ahYAR_6128GcTUEo"
        }
     },
     "type_filter":{
        "included_types":[
           "restaurant"
        ]
     },
     "price_levels":[
        "PRICE_LEVEL_INEXPENSIVE"
     ]
   }
   }'

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

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

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

{
  "count": "1025"
}

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

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

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

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