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

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

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

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

إنشاء مفاتيح واجهة برمجة التطبيقات

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

لإنشاء مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

وحدة التحكّم

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

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

2. في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.
   يعرض مربّع الحوار مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه مفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه حديثًا.
3. انقر على إغلاق.
   يظهر مفتاح واجهة برمجة التطبيقات الجديد في صفحة بيانات الاعتماد ضمن مفاتيح واجهة برمجة التطبيقات.
   (تذكَّر فرض قيود على مفتاح واجهة برمجة التطبيقات قبل استخدامه في مرحلة الإنتاج).

SDK للسحاب

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

• gcloud alpha services api-keys create

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

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

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

لتقييد مفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية:

وحدة التحكّم

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

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

2. اختَر مفتاح واجهة برمجة التطبيقات الذي تريد فرض قيود عليه. ستظهر صفحة موقع مفتاح واجهة برمجة التطبيقات.
3. ضمن قيود المفاتيح، اضبط القيود التالية:
• قيود التطبيق:
1. لقبول الطلبات من قائمة عناوين IP لخادم الويب التي تقدّمها، اختَر عناوين IP (خوادم الويب ومهام cron وغيرها) من قائمة قيود التطبيق. حدِّد عنوان IPv4 أو IPv6 واحدًا أو أكثر، أو شبكة فرعية باستخدام تدوين CIDR. يجب أن تتطابق عناوين IP مع عنوان المصدر الذي ترصده خوادم Google Maps Platform. في حال استخدام ترجمة عنوان الشبكة (NAT)، سيتوافق ذلك عادةً مع عنوان IP العلني لجهازك.
• القيود المفروضة على واجهة برمجة التطبيقات:
1. انقر على تقييد المفتاح.
2. اختَر Pollen API من القائمة المنسدلة اختيار واجهات برمجة التطبيقات. إذا لم تكن واجهة برمجة التطبيقات Pollen API مُدرَجة، عليك تفعيلها.
4. لإنهاء التغييرات، انقر على حفظ.
   

SDK للسحاب

إدراج المفاتيح الحالية

gcloud services api-keys list --project="PROJECT"

أزِل القيود الحالية المفروضة على المفتاح الحالي.

gcloud alpha services api-keys update "projects/PROJECT/keys/KEY_ID" \
    --clear-restrictions

يمكنك ضبط قيود جديدة على المفتاح الحالي.

gcloud alpha services api-keys update projects/PROJECT/locations/global/keys/KEY_ID \
    --api-target=service=pollen.googleapis.com
    --allowed-ips="IP_ADDRESS"

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

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

إضافة مفتاح واجهة برمجة التطبيقات إلى طلبك

يجب تضمين مفتاح واجهة برمجة التطبيقات مع كل طلب Pollen API. في المثال التالي، استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات.

https://pollen.googleapis.com/v1/forecast:lookup?key=YOUR_API_KEY

يجب توفُّر بروتوكول HTTPS للطلبات التي تستخدم مفتاح واجهة برمجة التطبيقات.

ملاحظة: عند استخدام خدمات الويب، يجب أن تكون جميع الأحرف الخاصة داخل المَعلمات بترميز عنوان URL. يجب ترميز عناوين URL بشكل صحيح لتكون صالحة، ويجب ألا تتجاوز 2048 حرفًا لجميع خدمات الويب. يُرجى الانتباه إلى هذا الحدّ عند إنشاء عناوين URL. قد تفرض المتصفّحات والخوادم المتعدّدة وخدمات الوكيل حدودًا مختلفة لعدد أحرف عناوين URL أيضًا.