הגדרת Geocoding API

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

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

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

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

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

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

יצירת טוקן OAuth

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

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

מידע על OAuth

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

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

אפשר גם להשתמש ב-Geocoding API כחלק מאפליקציה לנייד ל-Android או ל-iOS. מידע כללי על שימוש ב-OAuth עם Geocoding API, כולל מידע על ניהול אסימוני גישה לסביבות פריסה שונות, זמין במאמר שימוש ב-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 להמרת כתובות של מקומות לקואורדינטות (geocoding).

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

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

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

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

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

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

מתקינים ומפעילים את ה-CLI של gcloud.
מריצים את הפקודה gcloud הבאה במחשב המקומי כדי ליצור את קובץ פרטי הכניסה:
```
gcloud auth application-default login
```
מסך התחברות יוצג לפניכם. אחרי שמתחברים, פרטי הכניסה נשמרים בקובץ פרטי הכניסה המקומי שמשמש את 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.

עורכים את השדה 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/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

לוחצים על סמל ההעתקה בדוגמת הקוד, , כדי להעתיק את הפקודה curl.
מדביקים את הפקודה בחלון טרמינל ומריצים אותה.

התגובה היא אובייקט JSON:

פתרון בעיות

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