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

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

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

قبل البدء

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

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

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

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

وحدة التحكّم

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

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

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

Cloud SDK

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

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

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

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

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

وحدة التحكّم

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

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

  2. اختَر مفتاح واجهة برمجة التطبيقات الذي تريد ضبط قيود عليه. تظهر صفحة موقع مفتاح واجهة برمجة التطبيقات.
  3. ضِمن القيود الأساسية، اضبط القيود التالية:
    • قيود التطبيق:
      1. لقبول الطلبات من قائمة المواقع الإلكترونية التي تقدّمها، اختَر مُحيلو HTTP (مواقع الويب) من قائمة قيود التطبيق.
      2. حدد موقع ويب واحدًا أو أكثر من مواقع الإحالة. يُسمح باستخدام أحرف البدل لتفويض جميع النطاقات الفرعية (على سبيل المثال، يقبل *.google.com جميع المواقع الإلكترونية التي تنتهي بـ .google.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. حدد واجهة برمجة تطبيقات جافا سكريبت للخرائط من القائمة المنسدلة تحديد واجهات برمجة التطبيقات. إذا لم تكن واجهة برمجة تطبيقات جافا سكريبت للخرائط مدرجة، فسيلزمك تمكينها.
      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

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

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

يجب تضمين مفتاح واجهة برمجة التطبيقات مع كل طلب لواجهة برمجة تطبيقات 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_HERE",
    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>