הגדרת Geocoding API

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

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

מפתח API אסימון OAuth

יצירת טוקן OAuth

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

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

אתם יכולים לשלוח בקשות API ישירות לשרת של Google Maps API, או להשתמש בספריות לקוח כדי לפשט את הקוד. במפות Google יש ספריות לקוח ל-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 – משתמשים בפרמטר הזה בכל ה-methods של Geocoding API.
• ‫https://www.googleapis.com/auth/maps-platform.destinations – משתמשים רק עם SearchDestinations לשאילתות של יעד והגעה.
• ‫https://www.googleapis.com/auth/maps-platform.geocode.address – משתמשים רק עם GeocodeAddress להמרת כתובות לקואורדינטות (geocoding) קדימה.
• ‫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 לכל השיטות של Geocoding API. ההיקף הזה שימושי במהלך הפיתוח כי הוא היקף ברירת המחדל כשיוצרים אסימונים באמצעות ה-CLI של gcloud.

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

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

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

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

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

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

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

2. אימות באמצעות ה-CLI של gcloud:

   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, לוחצים על Copy בדוגמת הקוד.

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

פתרון בעיות

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