שימוש במפתחות API

כדי להגן על המוצרים של הפלטפורמה של מפות Google מפני שימוש לא מורשה, אנחנו מגבילים את הקריאות ל-API רק לאלה שמספקות פרטי כניסה תקינים לאימות. פרטי הכניסה האלה מופיעים בתור מפתח API – מחרוזת אלפאנומרית ייחודית שמקשרת את חשבון החיוב ב-Google לפרויקט ול-API או ל-SDK הספציפיים.

במדריך הזה מוסבר איך ליצור מפתח API לפלטפורמה של מפות Google, להגביל אותו ולהשתמש בו.

לפני שמתחילים

לפני שמתחילים להשתמש ב-Maps JavaScript API, צריך פרויקט עם חשבון לחיוב שבו מופעל Maps JavaScript API. מידע נוסף זמין במאמר הגדרה במסוף Cloud.

יצירת מפתחות API

מפתח ה-API הוא מזהה ייחודי שמאמת בקשות המשויכות לפרויקט שלכם לצורכי שימוש וחיובים. צריך להיות לפחות מפתח API אחד שמשויך לפרויקט.

כך יוצרים מפתח API:

המסוף

  1. עוברים לדף פלטפורמת מפות Google > פרטי כניסה.

    כניסה לדף Credentials

  2. בדף Credentials, לוחצים על Create credentials > API key.
    תיבת הדו-שיח API key created מציגה את מפתח ה-API החדש שיצרתם.
  3. לוחצים על סגירה.
    מפתח ה-API החדש מופיע בדף Credentials בקטע API keys.
    (חשוב לזכור להגביל את מפתח ה-API לפני שמשתמשים בו בסביבת הייצור).

Cloud SDK

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

מידע נוסף על Google Cloud SDK, על התקנת Cloud SDK ועל הפקודות הבאות:

הגבלת מפתחות API

Google ממליצה מאוד להגביל את מפתחות ה-API על ידי הגבלת השימוש בהם רק לממשקי ה-API הנחוצים לאפליקציה. הגבלת מפתחות ה-API מוסיפה אבטחה לאפליקציה על ידי הגנה עליה מפני בקשות לא רצויות. אתם אחראים על החיובים שנגרמו כתוצאה משימוש לרעה במפתחות API ללא הגבלה. למידע נוסף, ראו שיטות מומלצות לאבטחת API.

כדי להגביל מפתח API:

המסוף

  1. עוברים לדף פלטפורמת מפות Google > פרטי כניסה.

    כניסה לדף Credentials

  2. בוחרים את מפתח ה-API שרוצים להגדיר לו הגבלה. יופיע הדף של נכס מפתח ה-API.
  3. בקטע Key restrictions, מגדירים את ההגבלות הבאות:
    • הגבלות על אפליקציות:
      1. כדי לקבל בקשות מרשימת האתרים שסיפקתם, בוחרים באפשרות HTTP referers (web sites) מהרשימה Application restrictions.
      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://.
    • הגבלות על ממשקי API:
      1. לוחצים על Restrict key.
      2. בוחרים באפשרות Maps JavaScript API בתפריט הנפתח Select APIs. אם ממשק Maps JavaScript API לא מופיע ברשימה, צריך להפעיל אותו.
      3. אם בפרויקט שלכם נעשה שימוש ב-Places Library, צריך לבחור גם ב-Places API. באופן דומה, אם בפרויקט שלכם נעשה שימוש בשירותים אחרים ב-JavaScript API (שירות מסלולים, שירות מטריצת מרחקים, שירות גובה ו/או שירות קידוד גאוגרפי), עליכם גם להפעיל את ממשק ה-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/locations/global/keys/KEY_ID \
    --api-target=service=maps-backend.googleapis.com
    --allowed-referrers="referer"

מידע נוסף על Google Cloud SDK, על התקנת Cloud SDK ועל הפקודות הבאות:

הוספת מפתח ה-API לבקשה

חובה לכלול מפתח API בכל בקשה של ממשק API של JavaScript במפות Google. בדוגמה הבאה, מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם. 

<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>