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

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

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

قبل البدء

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

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

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

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

وحدة التحكم

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

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

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

Cloud SDK

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

يمكنك الاطّلاع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) في Google 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. اختر API JavaScript API من القائمة المنسدلة اختيار واجهات برمجة التطبيقات. إذا لم تكن Maps JavaScript API مدرَجة، عليك تفعيلها.
      3. إذا كان مشروعك يستخدم "مكتبة الأماكن"، حدِّد أيضًا واجهة برمجة تطبيقات الأماكن. وبالمثل، إذا كان مشروعك يستخدم خدمات أخرى في واجهة برمجة تطبيقات JavaScript (خدمة الاتجاهات و/أو خدمة مصفوفة المسافة و/أو خدمة الارتفاع و/أو خدمة الترميز الجغرافي)، عليك أيضًا تفعيل واختيار واجهة برمجة التطبيقات المناسبة في هذه القائمة.
  4. لإنهاء التغييرات التي أجريتها، انقر على حفظ.

Cloud 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/keys/KEY_ID" \
    --api-target="maps-backend.googleapis.com"
    --allowed-referrers="referer"

يمكنك الاطّلاع على مزيد من المعلومات عن حزمة تطوير البرامج (SDK) في Google Cloud، وتثبيت حزمة تطوير البرامج (SDK) في السحابة الإلكترونية والأوامر التالية:

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

يجب تضمين مفتاح واجهة برمجة التطبيقات مع كل طلب لواجهة برمجة تطبيقات JavaScript JavaScript. في المثال التالي، استبدل 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>