הגדרת Geocoding API

מפתחים באזור הכלכלי האירופי (EEA)

במאמר הזה מוסבר איך להתחיל להשתמש ב-Geocoding API.

בודקים שאתם עומדים בדרישות המוקדמות.

מפעילים את ה-API בפרויקט בענן ב-Google Cloud.

מגדירים מפתח API או OAuth כדי לשלוח בקשת API מאומתת.

כדי למנוע שימוש לא מורשה במוצרים של Google Maps Platform, צריך לכלול בקריאות ל-API מפתח API או אסימון OAuth. אתם יכולים לבחור את הליך ההגדרה שמתאים לסביבת הפריסה שלכם.

יצירת טוקן OAuth

‫Geocoding API תומך ב-OAuth 2.0 לצורך אימות. ‫Google תומכת בתרחישים נפוצים של OAuth 2.0, כמו תרחישים של שרת אינטרנט.

במאמר הזה מוסבר איך להעביר אסימון OAuth לקריאה ל-Geocoding API בסביבת הפיתוח. למידע נוסף על שימוש ב-OAuth בסביבת ייצור, אפשר לעיין במאמר בנושא שיטות אימות ב-Google.

אפשר לקרוא ל-Google Maps APIs ישירות על ידי שליחת בקשות API לשרת, או להשתמש בספריות לקוח כדי לפשט את הקוד. ב-Google Maps יש ספריות לקוח ל-Go, ל-Java, ל-Node.js ול-Python. מידע נוסף זמין במאמר ספריות לקוח של Geocoding API.

סקירה כללית של OAuth

יש כמה דרכים ליצור ולנהל אסימוני גישה באמצעות OAuth, בהתאם לסביבת הפריסה שלכם.

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

אפשר גם לשלב את Geocoding API באפליקציה לנייד ל-Android או ל-iOS. מידע נוסף על שימוש ב-OAuth וניהול אסימוני גישה לסביבות פריסה שונות זמין במאמר בנושא שימוש ב-OAuth 2.0 לגישה ל-Google APIs.

היקפי הרשאות OAuth

כדי להשתמש ב-OAuth עם Geocoding API, צריך להקצות לאסימון OAuth את ההיקף הנכון. ‫Geocoding API תומך בהיקפים הבאים:

  • ‫https://www.googleapis.com/auth/maps-platform.geocode— לשימוש בכל השיטות של Geocoding API.
  • ‫https://www.googleapis.com/auth/maps-platform.geocode.address—לשימוש רק עם GeocodeAddress לגיאו-קידוד קדימה.
  • ‫https://www.googleapis.com/auth/maps-platform.geocode.location—לשימוש רק עם GeocodeLocation להמרת קואורדינטות לכתובות (reverse geocoding).
  • ‫https://www.googleapis.com/auth/maps-platform.geocode.place—לשימוש רק עם GeocodePlace לגיאו-קידוד של מקומות.

אפשר גם להשתמש בהיקף הכללי https://www.googleapis.com/auth/cloud-platform לכל ה-methods של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח כי הוא היקף ברירת המחדל כשיוצרים אסימונים באמצעות ה-CLI של gcloud.

דוגמה: התנסות בקריאות ל-API בארכיטקטורת REST בסביבת הפיתוח המקומית

אם אין לכם סביבה שיוצרת טוקנים ואתם רוצים לנסות את Geocoding API עם טוקן OAuth, אתם יכולים להשתמש בתהליך שמתואר בקטע הזה.

בדוגמה הזו נסביר איך להשתמש באסימון OAuth שסופק על ידי Application Default Credentials ‏ (ADC) כדי לבצע את הקריאה. במאמר אימות באמצעות ספריות לקוח תוכלו לקרוא מידע נוסף על שימוש ב-ADC כדי לקרוא ל-Google APIs באמצעות ספריות לקוח.

התהליך הבא של REST מיועד רק לפיתוח או לבדיקה, ולא לייצור.

דרישות מוקדמות

כדי לשלוח בקשת REST באמצעות ADC, צריך קודם להשתמש ב-CLI של gcloud כדי לספק ל-ADC את פרטי הכניסה:

  1. מתקינים ומפעילים את gcloud CLI. למידע נוסף, ראו התקנת ה-CLI של gcloud.

  2. אימות באמצעות gcloud CLI:

    gcloud auth application-default login

  3. משלימים את תהליך הכניסה כדי לשמור את פרטי הכניסה בקובץ פרטי הכניסה המקומי שמשמש את ADC.

מידע נוסף זמין במאמר הגדרת ADC לסביבת פיתוח מקומית.

שליחת בקשת REST

בדוגמה הזו, מעבירים שתי כותרות בקשה:

  • מעבירים את טוקן ה-OAuth בכותרת Authorization באמצעות הפקודה הבאה כדי ליצור את הטוקן:

    gcloud auth application-default print-access-token

    לאסימון שמוחזר יש היקף של https://www.googleapis.com/auth/cloud-platform.

  • מעבירים את המזהה או השם של הפרויקט בענן ב-Google Cloud שבו מופעל חיוב בכותרת X-Goog-User-Project.

כדי לקרוא ל-Geocoding API באמצעות אסימון OAuth, מבצעים את השלבים הבאים:

  1. בדוגמת הקוד הבאה, מחליפים את PROJECT_ID במזהה הפרויקט ב-Google Cloud:

    curl -X GET -H 'Content-Type: application/json' \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

  2. כדי להעתיק את הפקודה curl, לוחצים על העתקה בדוגמת הקוד.

  3. מדביקים את הפקודה בחלון טרמינל ומריצים אותה.

פתרון בעיות

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