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

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

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

قبل البدء

قبل البدء في استخدام واجهة برمجة التطبيقات Maps JavaScript API، تحتاج إلى مشروع يتضمّن حساب فوترة ويكون فيه Maps JavaScript API مفعّلاً. لمزيد من المعلومات، يُرجى الاطّلاع على الإعداد في وحدة تحكّم Cloud.

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

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

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

وحدة التحكّم

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

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

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

SDK للسحاب

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

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

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

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

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

وحدة التحكّم

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

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

  2. اختَر مفتاح واجهة برمجة التطبيقات الذي تريد فرض قيود عليه. ستظهر صفحة موقع مفتاح واجهة برمجة التطبيقات.
  3. ضمن قيود المفاتيح، اضبط القيود التالية:
    • قيود التطبيق:
      1. لقبول الطلبات من قائمة المواقع الإلكترونية التي تقدّمها، اختَر مُحيلو HTTP (المواقع الإلكترونية) من قائمة قيود التطبيقات.
      2. حدِّد موقعًا إلكترونيًا واحدًا أو أكثر من المواقع الإلكترونية المُحيلة. يمكنك استخدام أحرف البدل لتفويض جميع النطاقات الفرعية (على سبيل المثال، يقبل https://*.google.com جميع المواقع الإلكترونية التي تنتهي بحرف .google.com عند الوصول إليها من خلال HTTPS). يُرجى العِلم أنّه في حال تحديد www.domain.com، سيعمل كحرف بدل www.domain.com/*، و سيمنح الإذن لأي مسار فرعي على اسم المضيف هذا. حدِّد مخطّطَي المُحيلَين https:// وhttp:// كما هو. بالنسبة إلى بروتوكولات عناوين URL الأخرى، يجب استخدام تمثيل خاص. على سبيل المثال، غيِّر التنسيق file:///path/to/ إلى __file_url__//path/to/*. بعد تفعيل المواقع الإلكترونية، احرص على تتبُّع معدّل الاستخدام للتأكّد من أنّه يلبّي توقعاتك. البروتوكولات المتوافقة هي: about:// وapp:// وapplewebdata:// asset:// وchrome:// وcontent:// file:// وftp:// وionic:// local:// وms-appx:// وms-appx-web:// ms-local-stream:// وprism:// وqrc:// res:// وsaphtmlp://.
    • القيود المفروضة على واجهة برمجة التطبيقات:
      1. انقر على تقييد المفتاح.
      2. اختَر Maps JavaScript API من القائمة المنسدلة اختيار واجهات برمجة التطبيقات. إذا لم تكن واجهة برمجة التطبيقات JavaScript لـ "خرائط Google" مُدرَجة، عليك تفعيلها.
      3. إذا كان مشروعك يستخدم "مكتبة الأماكن"، اختَر أيضًا Places API. وبالمثل، إذا كان مشروعك يستخدم خدمات أخرى في JavaScript API (خدمة الاتجاهات، خدمة Distance Matrix، خدمة Elevation، و/أو خدمة ترميز المواقع الجغرافية)، عليك أيضًا تفعيل واجهة برمجة التطبيقات المقابلة واختيارها في هذه القائمة.
  4. لإنهاء التغييرات، انقر على حفظ.

SDK للسحاب

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

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

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

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

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

gcloud services api-keys update projects/PROJECT/locations/global/keys/KEY_ID \
    --api-target=service=maps-backend.googleapis.com
    --allowed-referrers="referer"

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

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

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

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>