إرشادات الأمان في "منصة خرائط Google"

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

توضّح لك أفضل الممارسات هذه كيفية تأمين إذن الوصول إلى "منصة خرائط Google".

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

بالإضافة إلى تطبيق قيود على التطبيقات ومفاتيح واجهة برمجة التطبيقات، اتّبِع أي ممارسات أمان تنطبق على منتجات معيّنة من Google Maps Platform. على سبيل المثال، اطّلِع على Maps JavaScript API أدناه في القيود المقترَحة على التطبيقات وواجهات برمجة التطبيقات.

إذا كانت مفاتيح واجهة برمجة التطبيقات قيد الاستخدام، راجِع الاقتراحات أدناه في قسم إذا كنت تقيّد مفتاح واجهة برمجة تطبيقات قيد الاستخدام.

لمزيد من التفاصيل حول التواقيع الرقمية التي تتيحها واجهة Maps Static API وواجهة Street View Static API، يُرجى الاطّلاع على دليل التواقيع الرقمية.

أفضل الممارسات المقترَحة

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

يُنصح باستخدامها في جميع حالات استخدام مفتاح واجهة برمجة التطبيقات

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

استخدام مفاتيح واجهة برمجة تطبيقات منفصلة لكل تطبيق

حذف مفاتيح واجهة برمجة التطبيقات غير المستخدَمة

التحقّق من استخدام مفتاح واجهة برمجة التطبيقات

توخّي الحذر عند تغيير مفاتيح واجهة برمجة التطبيقات

تقسيم الاستخدام من جهة العميل ومن جهة الخادم إلى مشاريع منفصلة

إيقاف الخدمات غير المستخدَمة

اقتراحات إضافية للتطبيقات التي تعمل من جهة العميل

استخدام حِزم تطوير البرامج (SDK) من جهة العميل

إجراء طلبات آمنة لخدمات الويب من جهة العميل

اقتراحات إضافية للمواقع الإلكترونية أو التطبيقات من جهة العميل التي تستخدم واجهات برمجة التطبيقات Static Web APIs

حماية استخدام Static Web API

اقتراحات إضافية للتطبيقات من جهة الخادم التي تستخدم خدمات الويب

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

استخدام OAuth للتطبيقات من جهة الخادم

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

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

• بعد تغيير المفتاح، عليك تعديل جميع تطبيقاتك باستخدام مفاتيح واجهة برمجة التطبيقات الجديدة، حسب الحاجة.

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

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

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

• إذا تم اختراق مفتاح واجهة برمجة التطبيقات، عليك اتّخاذ إجراءات سريعة لتأمينه وإيقاف إساءة استخدامه. في تطبيقات Android وiOS، لا يتم استبدال المفاتيح إلا بعد أن يحدّث العملاء تطبيقاتهم. تعدّ عملية تعديل المفاتيح أو استبدالها في صفحات الويب أو التطبيقات من جهة الخادم أسهل بكثير، ولكنها قد تتطلّب مع ذلك تخطيطًا دقيقًا وعملاً سريعًا.

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

مزيد من المعلومات

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

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

من أفضل الممارسات تقييد مفاتيح واجهة برمجة التطبيقات دائمًا بنوع واحد من قيود التطبيقات وقيد واحد أو أكثر من قيود واجهة برمجة التطبيقات. للاطّلاع على القيود المقترَحة حسب واجهة برمجة التطبيقات أو حزمة SDK أو خدمة JavaScript، يُرجى الاطّلاع على القيود المقترَحة على التطبيقات وواجهات برمجة التطبيقات أدناه.

• قيود التطبيق يمكنك حصر استخدام مفتاح واجهة برمجة التطبيقات على منصات معيّنة، مثل تطبيقات Android أو iOS، أو مواقع إلكترونية معيّنة للتطبيقات من جهة العميل، أو عناوين IP أو الشبكات الفرعية CIDR معيّنة للتطبيقات من جهة الخادم التي تصدر طلبات REST API لخدمة الويب.

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

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

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

1. افتح صفحة بيانات اعتماد Google Maps Platform في Google Cloud Console.

2. اختَر مفتاح واجهة برمجة التطبيقات الذي تريد حظره.

3. في صفحة تعديل مفتاح واجهة برمجة التطبيقات، ضِمن قيود المفتاح، اختَر وضع قيود على التطبيق.

   

4. اختَر أحد أنواع القيود وقدِّم المعلومات المطلوبة وفقًا لقائمة القيود.

   نوع الحظر	الوصف
   المواقع الإلكترونية	حدِّد موقعًا إلكترونيًا واحدًا أو أكثر من المواقع الإلكترونية المُحيلة. مخطّطات معرّف الموارد المنتظم (URI) المتوافقة مع جميع الأنظمة هي https وhttp. لا نضمن عمل المخططات الأخرى بشكل صحيح، لأنّ متصفّحات الويب الحديثة لن ترسل عنوان `Referer` في الطلبات الصادرة لأسباب تتعلّق بالخصوصية. يجب دائمًا تقديم سلسلة المحيل بالكامل، بما في ذلك مخطط البروتوكول واسم المضيف والمنفذ الاختياري (مثلاً https://google.com). يمكنك استخدام أحرف البدل للسماح بجميع النطاقات الفرعية. على سبيل المثال، يقبل https://*.google.com جميع المواقع الإلكترونية التي تنتهي بـ .google.com. يجب توخّي الحذر عند السماح بإحالات إلى مصادر تتضمّن المسار الكامل، مثل https://google.com/some/path، لأنّ معظم متصفّحات الويب ستزيل المسار من الطلبات الواردة من مصادر متعددة لأسباب تتعلّق بالخصوصية.
   عناوين IP	حدِّد عنوانًا واحدًا أو أكثر من عناوين IPv4 أو IPv6، أو الشبكات الفرعية باستخدام تدوين CIDR. يجب أن تتطابق عناوين IP مع عنوان المصدر الذي ترصده خوادم Google Maps Platform. في حال استخدام ترجمة عنوان الشبكة (NAT)، يتوافق هذا العنوان عادةً مع عنوان IP العام لجهازك.
   تطبيقات Android	أضِف اسم حزمة Android (من ملف AndroidManifest.xml) وبصمة شهادة التوقيع SHA-1 لكل تطبيق Android تريد منحه الإذن. انقر على تطبيقات Android. انقر على + إضافة. أدخِل اسم الحزمة والملف المرجعي لشهادة SHA-1. على سبيل المثال: com.example.android.mapexample BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75 انقر على حفظ. هناك نوعان من الشهادات: شهادة تصحيح الأخطاء: لا تستخدِم هذا النوع من الشهادات إلا مع التطبيقات التي تختبرها ورموز أخرى غير مخصّصة للإنتاج. لا تحاول نشر تطبيق موقَّع بشهادة تصحيح الأخطاء. تنشئ أدوات حزمة تطوير البرامج (SDK) لنظام التشغيل Android هذه الشهادة تلقائيًا عند تشغيل إصدار تصحيح الأخطاء. شهادة الإصدار: استخدِم هذه الشهادة عندما تكون مستعدًا لإصدار تطبيقك في متجر تطبيقات. تنشئ أدوات حزمة تطوير البرامج (SDK) لنظام التشغيل Android هذه الشهادة عند تنفيذ إصدار علني. لمزيد من المعلومات حول توقيع تطبيقات Android والشهادات، يُرجى الاطّلاع على دليل توقيع التطبيق. إذا كنت تستخدم ميزة "توقيع التطبيق" من Play، يمكنك الاطّلاع على التعامل مع موفّري واجهات برمجة التطبيقات لمعرفة كيفية الحصول على الملف المرجعي لشهادة التوقيع. إذا كنت تدير مفتاح التوقيع الخاص بك، يمكنك الاطّلاع على توقيع تطبيقك بنفسك أو الرجوع إلى التعليمات الخاصة ببيئة الإنشاء.
   تطبيقات iOS	أضِف معرّف الحزمة لكل تطبيق iOS تريد تفويضه. اختَر تطبيقات iOS. انقر على + إضافة. أضِف رقم تعريف الحزمة لقبول الطلبات من تطبيق iOS الذي يحمل رقم التعريف هذا. انقر على حفظ.

   للحصول على اقتراحات بشأن حظر تطبيق، اطّلِع على حظر التطبيقات المقترَح.

5. انقر على حفظ.

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

1. افتح صفحة بيانات اعتماد Google Maps Platform في Google Cloud Console.

2. اختَر مفتاح واجهة برمجة التطبيقات الذي تريد حظره.

3. في صفحة تعديل مفتاح واجهة برمجة التطبيقات، ضِمن قيود واجهة برمجة التطبيقات:

   • انقر على مفتاح الحظر.

   • افتح اختيار واجهات برمجة التطبيقات واختَر واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) التي تريد أن يصل إليها تطبيقك باستخدام مفتاح واجهة برمجة التطبيقات.

   إذا لم تكن إحدى واجهات برمجة التطبيقات أو حِزم تطوير البرامج (SDK) مُدرَجة، عليك تفعيلها. لمزيد من التفاصيل، يُرجى الاطّلاع على كيفية تفعيل واجهة برمجة تطبيقات أو أكثر أو حزمة تطوير برامج واحدة أو أكثر.

   

4. انقر على حفظ.

   يصبح القيد جزءًا من تعريف مفتاح واجهة برمجة التطبيقات بعد هذه الخطوة. احرص على تقديم التفاصيل المناسبة واختَر حفظ لحفظ قيود مفتاح واجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على دليل الحصول على مفتاح واجهة برمجة التطبيقات في مستندات واجهة برمجة التطبيقات أو حزمة تطوير البرامج (SDK) المحدّدة التي تهمّك.

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

التحقّق من استخدام مفتاح واجهة برمجة التطبيقات

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

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

• اختيار النوع الصحيح من قيود التطبيقات باستخدام "مستكشف المقاييس"

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

تتيح لك تقارير المقاييس التالية تحديد واجهات برمجة التطبيقات التي تستخدم مفاتيح واجهة برمجة التطبيقات. استخدِم هذه التقارير لإجراء ما يلي:

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

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

1. انتقِل إلى مستكشف المقاييس في وحدة تحكّم Google Cloud.

2. سجِّل الدخول واختَر المشروع الذي تريد التحقّق من مفاتيح واجهة برمجة التطبيقات الخاصة به.

3. انتقِل إلى صفحة "مستكشف المقاييس" لنوع واجهة برمجة التطبيقات:

   • بالنسبة إلى مفاتيح واجهة برمجة التطبيقات التي تستخدم أي واجهة برمجة تطبيقات باستثناء Maps Embed API: انتقِل إلى صفحة مستكشف المقاييس.

   • بالنسبة إلى مفاتيح واجهة برمجة التطبيقات التي تستخدم Maps Embed API: انتقِل إلى مستكشف المقاييس.

4. افحص كل مفتاح من مفاتيح واجهة برمجة التطبيقات:

   1. انقر على إضافة فلتر.

   2. اختَر التصنيف credential_id.

   3. اختَر القيمة المقابلة للمفتاح الذي تريد فحصه.

   4. دوِّن واجهات برمجة التطبيقات التي يتم استخدام مفتاح واجهة برمجة التطبيقات هذا معها، وتأكَّد من أنّ هذا الاستخدام متوقّع.

   5. بعد الانتهاء، انقر على إزالة الفلتر delete في نهاية سطر الفلتر النشط لحذف الفلتر الإضافي.

5. كرِّر هذه الخطوات لأي مفاتيح متبقية.

6. قصر استخدام مفاتيح واجهة برمجة التطبيقات على واجهات برمجة التطبيقات المستخدَمة فقط.

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

اختيار نوع قيود التطبيق الصحيح باستخدام "مستكشف المقاييس"

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

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

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

1. انتقِل إلى مستكشف المقاييس في وحدة تحكّم Google Cloud.

2. سجِّل الدخول واختَر المشروع الذي تريد التحقّق من واجهات برمجة التطبيقات فيه.

3. انتقِل إلى صفحة "أداة استكشاف المقاييس" هذه: أداة استكشاف المقاييس.

4. افحص كل مفتاح من مفاتيح واجهة برمجة التطبيقات:

   1. انقر على إضافة فلتر.

   2. اختَر التصنيف credential_id.

   3. اختَر القيمة المقابلة للمفتاح الذي تريد فحصه.

   4. بعد الانتهاء، انقر على إزالة الفلتر delete في نهاية سطر الفلتر النشط لحذف الفلتر الإضافي.

5. كرِّر هذه الخطوات لأي مفاتيح متبقية.

6. بعد الحصول على نوع النظام الأساسي لمفاتيح واجهة برمجة التطبيقات، طبِّق قيود التطبيق على platform_type:

   استبدِل PLATFORM_TYPE_JS بما يلي : تطبيق قيود على المواقع الإلكترونية على المفتاح.

   PLATFORM_TYPE_ANDROID : تطبيق قيود تطبيقات Android على المفتاح

   PLATFORM_TYPE_IOS : تطبيق قيود تطبيقات iOS على المفتاح

   PLATFORM_TYPE_WEBSERVICE : قد تحتاج إلى الاعتماد على القيود المفروضة على عنوان IP في المفتاح لحظر استخدامه بشكل صحيح.

   للحصول على اقتراحات بشأن Maps Static API وStreet View Static API، يُرجى الاطّلاع على حماية استخدام واجهة برمجة تطبيقات الويب الثابتة.

   للاطّلاع على اقتراحات بشأن Maps Embed API، يُرجى مراجعة المواقع الإلكترونية التي تستخدم Maps Embed API.

   يستخدم مفتاح واجهة برمجة التطبيقات أنواعًا متعددة من الأنظمة الأساسية: لا يمكن تأمين حركة الزيارات بشكلٍ سليم باستخدام مفتاح واجهة برمجة تطبيقات واحد فقط. عليك نقل البيانات إلى مفاتيح واجهة برمجة تطبيقات متعددة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الانتقال إلى استخدام مفاتيح API متعددة.

استخدام مفاتيح واجهة برمجة تطبيقات منفصلة لكل تطبيق

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

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

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

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

إذا كانت الاقتراحات متاحة، ستظهر كخيارات معبّأة مسبقًا في صفحة بيانات اعتماد "منصة خرائط Google".

واجهات Google Maps Platform API وحِزم تطوير البرامج (SDK) المتوافقة مع الاقتراحات المبرمَجة

• ‫Maps JavaScript API، بما في ذلك خدمة Directions (الإصدار القديم)، خدمة Distance Matrix (الإصدار القديم)، خدمة Elevation، خدمة Geocoding فئة Place، أداة الإكمال التلقائي للأماكن (الجديدة)، واجهة برمجة التطبيقات لبيانات الإكمال التلقائي للأماكن، مكتبة الأماكن، خدمة الأماكن، أداة الإكمال التلقائي للأماكن، وPlaces UI Kit

• Maps Static API وStreet View Static API

• Maps Embed API

• حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android و"حزمة تطوير البرامج للتنقّل" على أجهزة Android و"حزمة تطوير برامج الأماكن" لأجهزة Android و"مجموعة عناصر واجهة مستخدم الأماكن" على Android

• حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS، وحزمة تطوير البرامج للتنقّل على أجهزة iOS، وحزمة تطوير البرامج بالاستناد إلى بيانات "أماكن Google" لتطبيقات iOS، وحزمة تطوير البرامج بالاستناد إلى بيانات "أماكن Google" المتوافقة مع Swift لتطبيقات iOS، وPlaces UI Kit على أجهزة iOS

أسباب عدم ظهور اقتراح أو ظهور اقتراح غير مكتمل

أسباب عدم ظهور أي اقتراح

• تستخدم (أيضًا) مفتاح واجهة برمجة التطبيقات في خدمات أخرى غير خدمات "منصة خرائط Google"، أو في خدمات "منصة خرائط Google" التي لا تتوافق بعد مع الاقتراحات التلقائية.

  إذا لاحظت استخدامًا في خدمات أخرى، لا تطبِّق الاقتراح بدون أوّلاً اتّخاذ الإجراءات التالية:

  1. تأكَّد من أنّ استخدام واجهة برمجة التطبيقات الذي يظهر لك في "مستكشف المقاييس" ضمن وحدة تحكّم Google Cloud هو استخدام مشروع.

  2. أضِف يدويًا الخدمات الناقصة إلى قائمة واجهات برمجة التطبيقات التي سيتم منحها الإذن.

  3. أضِف يدويًا أي قيود على التطبيقات غير متوفّرة للخدمات التي تمت إضافتها إلى قائمة واجهة برمجة التطبيقات. إذا كان التطبيق الآخر الذي أضفته يتطلّب نوعًا مختلفًا من قيود التطبيق، يُرجى الاطّلاع على نقل البيانات إلى مفاتيح واجهة برمجة تطبيقات متعددة.

• لا يتم استخدام مفتاح واجهة برمجة التطبيقات في حِزم تطوير البرامج (SDK) أو واجهات برمجة التطبيقات من جهة العميل.

• تستخدِم مفتاح واجهة برمجة التطبيقات في تطبيق أو موقع إلكتروني منخفض عدد الزيارات لم يشهد أي استخدام خلال آخر 60 يومًا.

• أنشأت مفتاحًا جديدًا مؤخرًا، أو نشرت مفتاحًا حاليًا في تطبيق جديد مؤخرًا. في هذه الحالة، ما عليك سوى الانتظار بضعة أيام أخرى حتى يتم تعديل الاقتراحات.

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

أسباب ظهور اقتراح غير مكتمل

• تستخدِم مفتاح واجهة برمجة التطبيقات في تطبيق أو موقع إلكتروني منخفض عدد الزيارات لم يشهد أي استخدام خلال آخر 60 يومًا.

• لقد بدأت مؤخرًا استخدام مفتاح حالي على واجهة برمجة تطبيقات أو خدمة جديدة، ولم تتم معالجة مقاييس الاستخدام المعدَّلة بعد من خلال مسار اقتراحات حصر مفتاح واجهة برمجة التطبيقات التلقائي. قد يستغرق نشر مقاييس الاستخدام بضعة أيام.

  إذا لاحظت استخدامًا في خدمات أخرى، لا تطبِّق الاقتراح بدون أوّلاً اتّخاذ الإجراءات التالية:

  1. تأكَّد من أنّ استخدام واجهة برمجة التطبيقات الذي يظهر لك في "مستكشف المقاييس" ضمن وحدة تحكّم Google Cloud هو استخدام مشروع.

  2. أضِف يدويًا الخدمات الناقصة إلى قائمة واجهات برمجة التطبيقات التي سيتم منحها الإذن.

  3. أضِف يدويًا أي قيود على التطبيقات غير متوفّرة للخدمات التي تمت إضافتها إلى قائمة واجهة برمجة التطبيقات. إذا كان التطبيق الآخر الذي أضفته يتطلّب نوعًا مختلفًا من قيود التطبيق، يُرجى الاطّلاع على نقل البيانات إلى مفاتيح واجهة برمجة تطبيقات متعددة.

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

أسباب ظهور اقتراحات غير مرئية في الرسوم البيانية

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

• عدد الزيارات وارد من Maps Embed API. للحصول على التعليمات، يُرجى الاطّلاع على تحديد واجهات برمجة التطبيقات التي تستخدم مفتاح واجهة برمجة التطبيقات.

• تكون الزيارات الواردة من التطبيق أو الموقع الإلكتروني خارج النطاق الزمني المتاح في "مستكشف المقاييس" ضمن Google Cloud Console.

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

1. افتح صفحة بيانات اعتماد Google Maps Platform في Google Cloud Console.

2. انقر على تطبيق القيود المقترَحة إذا كان هذا الخيار متاحًا.

   

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

4. تأكَّد من أنّ القيود التي تم ملؤها مسبقًا تتطابق مع المواقع الإلكترونية والتطبيقات التي تتوقّع استخدام مفتاح واجهة برمجة التطبيقات فيها.

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

   • إذا تبيّن لك أنّ تطبيقًا أو موقعًا إلكترونيًا أو واجهة برمجة تطبيقات غير مدرَجة في اقتراحك، يمكنك إضافتها يدويًا أو الانتظار بضعة أيام إلى أن يتم تعديل الاقتراح.

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

5. انقر على تطبيق.

ما يجب فعله إذا تم رفض طلبك بعد تطبيق توصية

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

حِزم تطوير البرامج (SDK) وواجهات برمجة التطبيقات من جهة العميل

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

عادةً ما تحذف المتصفحات الحديثة عنوان Referer في الطلبات الواردة من مصادر متعددة لأسباب تتعلّق بالخصوصية، وغالبًا ما تحوّله إلى Origin. ومع ذلك، يعتمد السلوك الدقيق على referrer-policy المطبَّق على الموقع الإلكتروني المضيف، وقد يختلف أيضًا استنادًا إلى متصفّح المستخدم وإصداره.

عادةً ما تحذف المتصفحات أو عروض الويب Referer بالكامل من أي طلبات صادرة في تطبيقات الويب التي تستخدم مخططات معرّفات URI مبهمة أو محلية لتحميل المحتوى، ما قد يؤدي إلى تعذُّر إرسال الطلبات باستخدام مفاتيح واجهة برمجة التطبيقات التي تتضمّن قيودًا على المواقع الإلكترونية.

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

تعليمات تحديد المشاكل وحلّها في التطبيقات المستندة إلى المتصفّح وعرض الويب:

• بالنسبة إلى Maps JavaScript API، يُرجى الاطّلاع على وحدة تحكّم تصحيح الأخطاء في المتصفّح للحصول على تفاصيل حول كيفية منح الإذن لتطبيقك.

  تتوفّر أنظمة معرّف الموارد المنتظم (URI) غير الشائعة بشكل جزئي. إذا كانت بعض أجزاء تطبيقك لا تعمل مع نظام URI غير مألوف، حتى بعد منح الإذن للمرجع المطلوب، من المحتمل أن تحتاج إلى استضافة تطبيقك عن بُعد على خادم وتحميله عبر HTTPS (أو HTTP).

  إذا كنت بحاجة إلى مساعدة بشأن أنظمة معرّفات الموارد المنتظمة (URI) غير الشائعة، يمكنك التواصل مع فريق الدعم.

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

  لا تتوافق مع أنظمة معرّفات الموارد المنتظمة (URI) غير الشائعة.

تطبيقات Android

استخدام Android Debug Bridge (adb) أو Logcat

تطبيقات iOS

يُرجى الاطّلاع على عرض رسائل السجلّ

التطبيقات التي ترسل طلبات إلى خدمات الويب مباشرةً

بالنسبة إلى التطبيقات التي تستدعي واجهة برمجة تطبيقات HTTPS REST الخاصة بـ "منصة خرائط Google" أو نقاط نهاية gRPC مباشرةً بدون حزمة تطوير برامج (SDK) من "منصة خرائط Google" من جهة العميل، يُرجى الاطّلاع على ما يلي:

تطبيقات Android وiOS

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

إذا كان تطبيقك يسجّل ردود الأخطاء من Maps Platform API، قد تكون التعليمات أعلاه الخاصة بحِزم SDK من جهة العميل مفيدة أيضًا في تحديد المشاكل وحلّها المتعلّقة بالمصادقة.

التطبيقات من جهة الخادم

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

التطبيقات المستندة إلى المتصفّح أو Webview

مع أنّ واجهات برمجة التطبيقات الأحدث من Google Maps Platform، مثل Maps Static API وStreet View Static API، ستتيح أيضًا إمكانية فرض قيود على عناوين URL الخاصة بالمحيل، يُرجى العِلم أنّ متصفّحات الويب أو عروض الويب ستفرض على الأرجح قيودًا على عنوان Referer ليقتصر على Origin في الطلبات الواردة من مصادر متعددة، ومن المحتمل أن تمنع إرساله تمامًا، مثلاً للموارد التي يتم الوصول إليها محليًا أو للموارد التي يتم عرضها عبر بروتوكولات أخرى غير HTTP أو HTTPS.

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

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

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

إذا لم تتمكّن من تحديد القيود التي يجب تطبيقها، اتّبِع الخطوات التالية:

1. دوِّن القيود الحالية للرجوع إليها في المستقبل.
2. أزِلها مؤقتًا أثناء التحقيق في المشكلة. يمكنك الاطّلاع على استخدامك بمرور الوقت باتّباع الخطوات الواردة في الاطّلاع على استخدام مفتاح واجهة برمجة التطبيقات.
3. يُرجى التواصل مع فريق الدعم إذا لزم الأمر.

حذف مفاتيح واجهة برمجة التطبيقات غير المستخدَمة

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

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

1. افتح صفحة بيانات اعتماد Google Maps Platform في Google Cloud Console.

2. اختَر مفتاح واجهة برمجة التطبيقات الذي تريد حذفه.

3. انقر على الزر حذف بالقرب من أعلى الصفحة.

4. في صفحة حذف بيانات الاعتماد، انقر على حذف.

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

توخَّ الحذر عند تدوير مفاتيح واجهة برمجة التطبيقات

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

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

• حاوِل أولاً فرض قيود على مفاتيح واجهة برمجة التطبيقات كما هو موضّح في فرض قيود على مفاتيح واجهة برمجة التطبيقات.

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

إذا لم تكن الاقتراحات السابقة ممكنة، وكان عليك تدوير مفتاح واجهة برمجة التطبيقات لمنع الاستخدام غير المصرّح به، اتّبِع الخطوات التالية:

1. افتح صفحة بيانات اعتماد Google Maps Platform في Google Cloud Console.

2. افتح مفتاح واجهة برمجة التطبيقات الذي تريد تدويره.

3. في أعلى الصفحة، انقر على تدوير المفتاح.

4. يمكنك اختياريًا تغيير اسم مفتاح واجهة برمجة التطبيقات.

5. انقر على إنشاء.

6. عدِّل تطبيقاتك لاستخدام المفتاح الجديد.

بعد تعديل تطبيقاتك لاستخدام المفتاح الجديد، احذف المفتاح القديم بالنقر على الزر حذف المفتاح السابق ضمن القسم "المفتاح السابق" في صفحة مفتاح واجهة برمجة التطبيقات الجديد.

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

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

1. تحديد التطبيقات التي تحتاج إلى مفاتيح جديدة:

   • تُعدّ تطبيقات الويب الأسهل في التحديث، لأنّك تتحكّم في كل الرموز البرمجية. خطِّط لتعديل جميع مفاتيح تطبيقاتك المستندة إلى الويب.
   • تكون تطبيقات الأجهزة الجوّالة أكثر صعوبة، لأنّه على عملائك تعديل تطبيقاتهم قبل أن يتمكّنوا من استخدام المفاتيح الجديدة.

2. إنشاء المفاتيح الجديدة وتقييدها: أضِف قيودًا على التطبيق وقيودًا واحدة على الأقل على واجهة برمجة التطبيقات. لمزيد من المعلومات، راجِع أفضل الممارسات المقترَحة.

3. إضافة المفاتيح الجديدة إلى تطبيقاتك: بالنسبة إلى تطبيقات الأجهزة الجوّالة، قد تستغرق هذه العملية شهورًا إلى أن يثبّت جميع المستخدمين آخر إصدار من التطبيق يتضمّن مفتاح واجهة برمجة التطبيقات الجديد.

تقسيم الاستخدام من جهة العميل ومن جهة الخادم إلى مشاريع منفصلة

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

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

ومع ذلك، بما أنّ القيود المفروضة على الحصة لكل مستخدم تؤثّر في التطبيقات من جهة العميل ومن جهة الخادم، إذا كنت تحتاج أيضًا إلى معدل نقل بيانات عالٍ لمهامك من جهة الخادم، يمكنك إعداد مشروع منفصل لحالة الاستخدام هذه، مع ضبطه على حد أعلى للحصة لكل مستخدم أو بدون أي حد على الإطلاق.

إيقاف الخدمات غير المستخدَمة

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

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

استخدام حِزم SDK من جهة العميل

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

سيسمح لك استخدام حِزم تطوير البرامج (SDK) من جهة العميل أيضًا بتبنّي آلية أمان أكثر تقدّمًا، مثل خدمة App Check من Firebase على مساحات واجهة برمجة التطبيقات في "منصة خرائط Google" التي تتيحها. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة استخدام App Check لتأمين مفتاح واجهة برمجة التطبيقات.

إذا لم تتوفّر حِزم SDK من جهة العميل لمنصتك، يُرجى الاطّلاع على مقالة تأمين طلبات خدمة الويب من جهة العميل.

للاطّلاع على مدى توفّر حِزم تطوير البرامج (SDK) من "منصة خرائط Google" من جهة العميل لمختلف المنصات، راجِع القيود المقترَحة على التطبيقات وواجهات برمجة التطبيقات.

حماية استخدام واجهة برمجة التطبيقات Static Web API

تشبه واجهات برمجة التطبيقات الثابتة على الويب، مثل Maps Static API وStreet View Static API، طلبات واجهات برمجة التطبيقات لخدمات الويب.

يمكنك طلب كليهما باستخدام واجهة برمجة تطبيقات REST عبر HTTPS، وعادةً ما يتم إنشاء عنوان URL لطلب البيانات من واجهة برمجة التطبيقات على الخادم. ومع ذلك، بدلاً من عرض استجابة JSON، تنشئ واجهات Static Web API صورة يمكنك تضمينها في رمز HTML الذي تم إنشاؤه. والأهم من ذلك، أنّ العميل من المستخدمين النهائيين هو الذي يستدعي خدمة "منصة خرائط Google"، وليس الخادم.

استخدام توقيع رقمي

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

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

حماية سر التوقيع

لحماية واجهات Static Web API، لا تضمِّن أسرار توقيع واجهة برمجة التطبيقات مباشرةً في الرمز البرمجي أو في شجرة المصدر، ولا تعرضها في تطبيقات من جهة العميل. اتّبِع أفضل الممارسات التالية لحماية أسرار التوقيع:

• إنشاء عناوين URL لطلبات موقع "خرائط Google" الثابت API وStreet View Static API الموقّعة من جهة الخادم عند عرض صفحة ويب أو استجابةً لطلب من تطبيقك على الأجهزة الجوّالة

  بالنسبة إلى محتوى الويب الثابت، يمكنك استخدام التطبيق المصغّر توقيع عنوان URL الآن في صفحة بيانات الاعتماد على "منصة خرائط Google" في Cloud Console.

  بالنسبة إلى محتوى الويب الديناميكي، يمكنك الاطّلاع على نماذج الرموز المتاحة لتوقيع طلبات عناوين URL.

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

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

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

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

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

استخدام OAuth للتطبيقات من جهة الخادم

‫OAuth 2.0 هو معيار مفتوح لتفويض الوصول.

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

بما أنّ حساب الخدمة قد يتضمّن أذونات واسعة النطاق، يُنصح باستخدام OAuth 2.0 لمنح الإذن بإجراء طلبات من خادم إلى خادم بين تطبيقات موثوقة من جهة الخادم يملكها المطوّر وخوادم Google Maps Platform.

بالنسبة إلى التطبيقات التي تعمل على أجهزة المستخدمين النهائيين، يُنصح باستخدام طرق مصادقة أخرى، مثل مفاتيح واجهة برمجة التطبيقات.

إذا أردت استخدام OAuth 2.0 للسماح بنقل البيانات من خادم إلى خادم، ابحث عن موضوع OAuth في مستندات واجهة برمجة التطبيقات.

على سبيل المثال، إليك موضوع OAuth الخاص بواجهة برمجة التطبيقات Address Validation API.

تأمين طلبات خدمة الويب من جهة العميل

إذا لم تتوفّر حِزم تطوير البرامج (SDK) من جهة العميل، يُرجى الاطّلاع على الاقتراحات أدناه.

استخدام خادم وكيل

يوفّر استخدام خادم وكيل آمن مصدرًا موثوقًا للتفاعل مع نقطة نهاية خدمة الويب في "منصة خرائط Google" من تطبيق من جهة العميل بدون الكشف عن مفتاح واجهة برمجة التطبيقات أو سر التوقيع أو حساب خدمة Google Cloud للمستخدمين غير المصرّح لهم.

النقاط الرئيسية:

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

• معالجة ردود "منصة خرائط Google" بعد إرسالها على خادم الوكيل فلترة البيانات التي لا يحتاج إليها العميل

لمزيد من المعلومات حول استخدام خادم وكيل، يُرجى الاطّلاع على Living Vicariously: Using Proxy Servers with the Google Data API Client Libraries.

تأمين طلبات الخدمة المباشرة على الويب المتوافق مع الأجهزة الجوّالة

إذا لم تتمكّن من إعداد خادم وكيل آمن لتطبيقك من جهة العميل، يمكنك تأمين تطبيقك باتّباع الخطوات التالية:

1. استخدام عناوين HTTP:

   • Android: استخدِم عنوانَي HTTP X-Android-Package وX-Android-Cert.

   • iOS: استخدِم عنوان HTTP X-Ios-Bundle-Identifier.

2. أضِف قيود التطبيق المناسبة إلى مفتاح Android أو iOS.

3. قبل التفكير في إصدار طلبات مباشرةً من تطبيقك على الأجهزة الجوّالة إلى خدمة ويب REST API في "منصة خرائط Google"، تأكَّد من رفض الطلبات التي تتضمّن معرّفات تطبيقات غير صحيحة على Android أو iOS.

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

نصائح لتطبيقات Android:

• قبل دمج تطبيق Android مع خدمات Google Maps Platform، تأكَّد من أنّ تنسيق معرّف تطبيقك (المعروف أيضًا باسم الحزمة) صحيح. للحصول على التفاصيل، يُرجى الاطّلاع على ضبط وحدة التطبيق في مستندات Android.

• لتمرير X-Android-Package مباشرةً من تطبيقك، ابحث عنه آليًا باستخدام Context.getPackageName().

• لتمرير X-Android-Cert مباشرةً من تطبيقاتك، احسب الملف المرجعي SHA-1 المطلوب لشهادات توقيع تطبيقك، والتي يمكن الوصول إليها من خلال PackageInfo.signingInfo.

• إذا كنت تفوّض تطبيق Android باستخدام Google Cloud Console، يُرجى العِلم أنّ واجهة المستخدم تتوقّع أن تكون بصمة SHA-1 عبارة عن سلسلة مفصولة بنقطتين، مثل: 00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33. ومع ذلك، تتوقّع أداة gcloud وواجهة برمجة التطبيقات لمفاتيح API السلسلة السداسية العشرية بدون محدّدات.

نصائح لتطبيقات iOS:

• قبل دمج تطبيق iOS مع خدمات "منصة خرائط Google"، تأكَّد من أنّ معرّف الحزمة منسَّق بشكل صحيح.

• يجب عادةً تمرير معرّف الحزمة الخاص بالحزمة الرئيسية في عنوان X-Ios-Bundle-Identifier عند منح الإذن لتطبيق iOS.

لمزيد من المعلومات، يُرجى الرجوع إلى المقالتَين إدارة مفاتيح واجهة برمجة التطبيقات و استخدام مفاتيح واجهة برمجة التطبيقات للوصول إلى واجهات برمجة التطبيقات.

استضافة تطبيقاتك المستندة إلى المتصفّح على خادم

تتيح لك أُطر العمل، مثل Apache Cordova، إنشاء تطبيقات مختلطة متعددة المنصات تعمل داخل عرض ويب. ومع ذلك، لا يمكن ضمان عمل قيود المواقع الإلكترونية التي تستخدم مفتاح واجهة برمجة التطبيقات بشكل صحيح، إلا إذا تم تحميل تطبيق الويب باستخدام HTTP أو HTTPS من موقع إلكتروني تتحكّم فيه وقد منحته الإذن.

في كثير من الحالات، ستؤدي الموارد المجمّعة أو المحمَّلة محليًا من داخل تطبيق مختلط أو التي يتم الوصول إليها باستخدام عنوان URL لملف محلي إلى منع عمل التفويض المستند إلى الإحالة، لأنّ محرك المتصفح الذي يشغّل طريقة عرض الويب سيحذف إرسال العنوان Referer. لتجنُّب ذلك، استضِف تطبيقات الويب من جهة الخادم وليس من جهة العميل.

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

استخدام App Check لتأمين مفتاح واجهة برمجة التطبيقات

تتيح لك بعض حِزم تطوير البرامج وواجهات برمجة التطبيقات في "خرائط Google" إمكانية الدمج مع خدمة App Check من Firebase. توفّر خدمة App Check الحماية للمكالمات من تطبيقك إلى "منصة خرائط Google" من خلال حظر الزيارات التي تأتي من مصادر أخرى غير التطبيقات المشروعة. ويتم ذلك من خلال البحث عن رمز مميّز من موفّر خدمة إثبات صحة الجهاز. يساعد دمج تطبيقاتك مع خدمة App Check في الحماية من الطلبات الضارة، وبالتالي لن يتم تحصيل رسوم منك مقابل طلبات البيانات من واجهة برمجة التطبيقات غير المصرَّح بها.

تعليمات دمج App Check:

• Places SDK for iOS
• Places SDK for Android
• Maps JavaScript API
• فئة المكان، Maps JavaScript API

التعامل مع الاستخدام غير المصرّح به لمفتاح واجهة برمجة التطبيقات

إذا رصدت استخدامًا غير مصرّح به لمفتاح واجهة برمجة التطبيقات، اتّبِع الخطوات التالية لحلّ المشكلة:

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

   • تقييد مفاتيح واجهة برمجة التطبيقات
   • نقل البيانات إلى مفاتيح واجهة برمجة تطبيقات متعددة
   • استخدام مفاتيح واجهة برمجة تطبيقات منفصلة لكل تطبيق

2. إذا كنت تستخدم حِزمة تطوير البرامج (SDK) الخاصة بخدمة "الأماكن" أو واجهة برمجة تطبيقات JavaScript للخرائط، يمكنك أيضًا استخدام App Check لتأمين مفتاح واجهة برمجة التطبيقات.

3. لا تستبدِل المفاتيح أو تديرها إلا إذا كان الشرط التالي صحيحًا:

   • رصد استخدام غير مصرّح به للمفاتيح التي لا يمكن حظرها أو التي تم حظرها بالفعل، ولا ينطبق ذلك على App Check.

   • إذا كنت تريد اتّخاذ إجراءات أسرع لتأمين مفتاح واجهة برمجة التطبيقات وإيقاف إساءة الاستخدام، حتى لو كان ذلك سيؤثّر في الزيارات المشروعة من تطبيقك

   قبل المتابعة، يُرجى قراءة المقالة توخَّ الحذر عند تدوير مفاتيح واجهة برمجة التطبيقات.

4. إذا استمرّت المشاكل أو كنت بحاجة إلى المساعدة، يُرجى التواصل مع فريق الدعم.

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

تقترح الأقسام التالية قيودًا مناسبة على التطبيقات وواجهات برمجة التطبيقات لكل واجهة برمجة تطبيقات أو حزمة تطوير برامج أو خدمة من "منصة خرائط Google".

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

تنطبق الإرشادات التالية بشأن قيود واجهة برمجة التطبيقات على جميع خدمات Google Maps Platform:

• احصر استخدام مفتاح واجهة برمجة التطبيقات على واجهات برمجة التطبيقات التي تستخدمها فقط، مع استثناءات مما يلي:

  • إذا كان تطبيقك يستخدم حزمة تطوير البرامج (SDK) الخاصة بخدمة "الأماكن في Android" أو حزمة تطوير البرامج (SDK) الخاصة بخدمة "الأماكن في iOS"، عليك منح الإذن لاستخدام واجهة Places API (New) أو Places API، وذلك حسب إصدارات حزمة تطوير البرامج (SDK) التي تستخدمها. ¹

  • إذا كان تطبيقك يستخدم Maps JavaScript API، عليك دائمًا منح الإذن باستخدامها على مفتاحك.

  • إذا كنت تستخدم أيضًا أيًا من خدمات Maps JavaScript API التالية، عليك أيضًا تفويض واجهات برمجة التطبيقات المقابلة:

    الخدمة	قيود واجهة برمجة التطبيقات
    خدمة "الاتجاهات" (الإصدار القديم)	Directions API (الإصدار القديم)
    خدمة Distance Matrix (الإصدار القديم)	Distance Matrix API (الإصدار القديم)
    Elevation Service	Elevation API
    خدمة الترميز الجغرافي	Geocoding API
    فئة المكان، أداة الإكمال التلقائي للأماكن (جديدة) & واجهة برمجة التطبيقات الخاصة ببيانات الإكمال التلقائي للأماكن	‫Places API (جديدة)2
    Places Library وPlaces Service وPlace Autocomplete Widget	Places API2

¹ لمزيد من التفاصيل، راجِع مستندات حزمة تطوير البرامج Places SDK لنظام التشغيل Android وحزمة تطوير البرامج Places SDK لنظام التشغيل iOS.

² إذا لم تكن متأكدًا مما إذا كنت بحاجة إلى تفويض Places API (الجديدة) أو Places API، يمكنك الاطّلاع على مستندات Maps JavaScript API.

إليك بعض الأمثلة:

• أنت تستخدم حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android وحزمة تطوير البرامج بالاستناد إلى بيانات "أماكن Google" لتطبيقات Android، لذا عليك تضمين حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android وواجهة Places API (الجديدة) كقيود على واجهة برمجة التطبيقات.

• يستخدم موقعك الإلكتروني خدمة الارتفاع في Maps JavaScript API وMaps Static API، لذا عليك إضافة قيود على واجهة برمجة التطبيقات لجميع واجهات برمجة التطبيقات التالية:

  • Maps JavaScript API
  • Elevation API
  • Maps Static API

قيود التطبيقات المقترَحة

المواقع الإلكترونية

بالنسبة إلى المواقع الإلكترونية التي تستخدم خدمات Maps JavaScript API أو Maps Static API أو Street View Static API أو تستدعي خدمات Google Maps Platform الحديثة مباشرةً عبر HTTPS REST API أو gRPC، استخدِم قيود التطبيق المواقع الإلكترونية:

خدمة "الاتجاهات" (الإصدار القديم) خدمة Distance Matrix (الإصدار القديم) Elevation Service خدمة ترميز المواقع الجغرافية

Maps JavaScript API1 مكتبة الأماكن2 Maps Static API3 ‫Street View Static API3

¹ بالنسبة إلى تطبيقات الأجهزة الجوّالة، ننصحك باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل Android وحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لنظام التشغيل iOS الأصليتَين.

² بالنسبة إلى تطبيقات الأجهزة الجوّالة، ننصحك باستخدام Places SDK لنظام التشغيل Android وPlaces SDK لنظام التشغيل iOS الأصليَين.

³ يمكنك أيضًا الاطّلاع على حماية استخدام واجهة برمجة التطبيقات للويب الثابت.

المواقع الإلكترونية التي تستخدم Maps Embed API

على الرغم من أنّ استخدام Maps Embed API لا يتطلّب أي رسوم، عليك مع ذلك حصر أي مفتاح API مستخدَم لمنع إساءة الاستخدام في الخدمات الأخرى.

أفضل الممارسات: أنشئ مفتاح واجهة برمجة تطبيقات منفصلاً لاستخدام Maps Embed API، واقتصر على استخدام هذا المفتاح مع Maps Embed API فقط. يوفّر هذا القيد أمانًا كافيًا للمفتاح، ما يمنع استخدامه بدون إذن على أي خدمة أخرى من Google. للحصول على تحكّم كامل في الأماكن التي يمكن استخدام مفتاح Maps Embed API فيها، تنصح Google أيضًا بتطبيق قيود استخدام المواقع الإلكترونية.

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

التطبيقات والخوادم التي تستخدم خدمات الويب

بالنسبة إلى الخوادم والتطبيقات من جهة العميل من الشبكات الداخلية الموثوق بها للشركات التي تستخدم خدمات الويب مع مفاتيح واجهة برمجة التطبيقات، استخدِم قيود تطبيق IP addresses.

الاستخدام للتطبيقات والخوادم التي تستخدم واجهات برمجة التطبيقات هذه:

Address Validation API Aerial View API Air Quality API Directions API (الإصدار القديم)4 Distance Matrix API (الإصدار القديم)4 Elevation API Geocoding API5 Geolocation API6 Map Tiles API

Maps Datasets API Places API (إصدار جديد)7 Places API6 Roads API Routes API4 Pollen API Solar API Time Zone API8 Weather API

⁴ بالنسبة إلى تطبيقات الأجهزة الجوّالة، ننصحك باستخدام حزمة تطوير البرامج للتنقّل.

^‫5 لاستخدام الأجهزة الجوّالة بأمان، استخدِم خادم وكيل آمنًا.

⁶ بالنسبة إلى التطبيقات من جهة العميل، ننصحك باستخدام خدمة تحديد الموقع الجغرافي الأصلية التي توفّرها المنصة، مثل تحديد الموقع الجغرافي من W3C لمتصفحات الويب، أو LocationManager أو Fused Location Provider API لنظام Android، أو إطار عمل Core Location من Apple لنظام iOS.

⁷ بالنسبة إلى تطبيقات الأجهزة الجوّالة، ننصحك باستخدام حزمة تطوير البرامج (SDK) الأصلية الخاصة بخدمة "أماكن Google" لنظام التشغيل Android وحزمة تطوير البرامج (SDK) الخاصة بخدمة "أماكن Google" لنظام التشغيل iOS.

^‫8 لاستخدام آمن من جهة العميل، استخدِم خادم وكيل آمنًا.

تطبيقات Android

بالنسبة إلى التطبيقات على Android، استخدِم قيود التطبيق Android apps. يُستخدَم مع التطبيقات التي تستخدم حِزم SDK التالية:

• حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات Android
• Places SDK for Android
• حزمة تطوير البرامج للتنقّل على أجهزة Android

بالإضافة إلى ذلك، يمكنك منع إدخال مفاتيح واجهة برمجة التطبيقات عن طريق الخطأ في نظام التحكّم بالإصدارات من خلال استخدام إضافة Secrets Gradle لإدخال الأسرار من ملف محلي بدلاً من تخزينها في ملف البيان AndroidManifest.xml.

تطبيقات iOS

بالنسبة إلى التطبيقات على أجهزة iOS، استخدِم قيود تطبيق iOS apps. الاستخدام للتطبيقات والخوادم التي تستخدم حِزم SDK هذه:

• حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" لتطبيقات iOS
• Places SDK for iOS
• حزمة تطوير البرامج للتنقّل على أجهزة iOS

محتوى إضافي للقراءة

• إدارة مفاتيح واجهة برمجة التطبيقات
• استخدام مفاتيح واجهة برمجة التطبيقات للوصول إلى واجهات برمجة التطبيقات
• تحسين استخدام "منصة خرائط Google" من خلال الحصص (فيديو)
• كيفية إنشاء مفاتيح واجهة برمجة التطبيقات وتقييدها في "منصة خرائط Google" (فيديو)
• تقييد مفاتيح واجهة برمجة التطبيقات
• تأمين مفاتيح واجهة برمجة التطبيقات عند استخدام واجهات برمجة التطبيقات Static Maps وStreet View
• ‫15 من أفضل الممارسات في "منصة خرائط Google"