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

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

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

قبل البدء

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

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

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

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

وحدة التحكّم

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

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

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

Cloud SDK

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

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

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

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

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

وحدة التحكّم

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

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

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

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

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