ביצוע הקריאות הראשונות ל-API

ביצוע קריאות HTTP

ניתן לקרוא ל-Street View Publish API באמצעות מספר כלים כמו curl, wget, Postman. ברוב המקרים תצטרכו להשתמש בשפת תכנות לבחירתכם כדי לבנות אפליקציית לקוח. שמשתמש ב-API, אבל המדריך הזה ינחה אתכם בשלבים הבסיסיים לפקודות נפרדות.

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

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

1. יש צורך בחשבון Google כדי לגשת ל-Google API Console, לבקש מפתח API ולרשום את האפליקציה.

2. יוצרים פרויקט ב-Google Developers Console ומקבלים פרטי כניסה להרשאה כדי שהאפליקציה תוכל לשלוח בקשות API.

3. אחרי שיוצרים את הפרויקט, צריך לוודא ש-Street View Publish API הוא אחד מהשירותים שהאפליקציה רשומה לשימוש בהם:

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

4. במדריך האימות מוסבר איך מטמיעים הרשאת OAuth 2.0.

5. להכיר את מושגי הליבה של פורמט הנתונים JavaScript Object Notation (JSON). JSON הוא פורמט נתונים נפוץ ובלתי תלוי בשפה, שבו מבני נתונים שרירותיים מיוצגים באמצעות טקסט פשוט. מידע נוסף זמין בכתובת json.org.

קבלת מפתח API

למטרות אימות ומכסה, עליך להשתמש ב-Google Street View Publish API עם פרטי כניסה שנוצרו מ-Developer Console שלך.

1. עוברים אל Credentials בדף Developers Console.
2. אם כבר יש לכם מפתח API, תוכלו להשתמש בערך שלו. אחרת, כדי ליצור אסימון חדש, בוחרים באפשרות API key בתפריט New credentials (פרטי כניסה חדשים).

קבלת אסימון גישה

1. עוברים אל Playground 2.0 של Google Developers.
2. לוחצים על תפריט ההגדרות (סמל גלגל השיניים בפינה השמאלית העליונה), מסמנים את האפשרות שימוש בפרטי הכניסה שלך ל-OAuth ומזינים את Client ID ואז Client secret בשדות המתאימים, ולאחר מכן לוחצים על סגירה.
3. תחת שלב 1: בחירה ו- Certificate APIs, מזינים את היקף ה-API https://www.googleapis.com/auth/streetviewpublish בשדה Input your own scopes (הזנת היקפים), לוחצים על Authorize APIs. א' ייפתח דף חדש כדי לאשר שברצונך לתת הרשאה ל-API.
4. לוחצים על החלפת קוד הרשאה לאסימונים. הפעולה הזו תאכלס את אסימון גישה, שיכיל את אסימון הגישה לשימוש לשלב הבא. התוקף של אסימון הגישה יפוג אחרי 60 דקות. אפשר לבחור באפשרות מתבצע רענון אוטומטי של האסימון לפני שהתוקף שלו יפוג. פעולה זו תיצור אסימון חדש.

שליחה של בקשת HTTP

אחרי שמקבלים את מפתח ה-API ואסימון הגישה, אפשר להריץ את הפקודה הבאה במעטפת כדי לבצע קריאת HTTP לשירות. בדוגמה הבאה, אנחנו ביצוע קריאה ל-method /v1/photo:startUpload.

    $ curl --request POST \
    --url 'https://streetviewpublish.googleapis.com/v1/photo:startUpload?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Length: 0'
  

בקשות לדוגמה

אחרי שתרגישו בנוח לשלוח את בקשת ה-HTTP שלמעלה, נסו להשתמש שיטות. בהמשך מוצגות מגוון שיחות.

המערכת מקבלת רשימה של התמונות שלך

    $ curl --request GET \
    --url 'https://streetviewpublish.googleapis.com/v1/photos?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN'
  

בתהליך קבלת תמונה

    $ curl --request GET \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY' \
    --header 'authorization: Bearer YOUR_ACCESS_TOKEN'
  

העלאת תמונה

כדי ליצור תמונה נדרשים שלוש שיחות נפרדות. הקריאה הראשונה תחזיר כתובת URL להעלאה, שיהיה בשימוש בקריאה השנייה כדי להעלות את הבייטים של התמונות. אחרי העלאת הבייטים של התמונות, הקריאה השלישית מעלה את המטא-נתונים של התמונה ומחזירה את התעודה המזהה עם התמונה.

1. בקשת כתובת URL להעלאה

           $ curl --request POST \
           --url 'https://streetviewpublish.googleapis.com/v1/photo:startUpload?key=YOUR_API_KEY' \
           --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
           --header 'Content-Length: 0'
         

2. העלאת הבייטים של התמונות לכתובת ה-URL להעלאה

           $ curl --request POST \
           --url 'UPLOAD_URL' \
           --upload-file 'PATH_TO_FILE' \
           --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
         

3. העלאת המטא-נתונים של התמונה

           $ curl --request POST \
           --url 'https://streetviewpublish.googleapis.com/v1/photo?key=YOUR_API_KEY' \
           --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
           --header 'Content-Type: application/json' \
           --data '{
                     "uploadReference":
                     {
                       "uploadUrl": "UPLOAD_URL"
                     },
                     "pose":
                      {
                        "heading": 105.0,
                        "latLngPair":
                        {
                          "latitude": 46.7512623,
                          "longitude": -121.9376983
                        }
                     },
                     "captureTime":
                     {
                       "seconds": 1483202694
                     },
                   }'
         

עדכון תמונה מתבצע

   $ curl --request PUT \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY&updateMask=pose.latLngPair' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
               "pose":
               {
                 "latLngPair":
                 {
                   "latitude": 46.7512624,
                   "longitude": -121.9376982
                 }
               }
             }'
  

עדכון מספר תמונות בבת אחת

   $ curl --request POST \
    --url 'https://streetviewpublish.googleapis.com/v1/photos:batchUpdate?key=YOUR_API_KEY' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
              "updatePhotoRequests": [
                  {
                      "photo": {
                          "photoId": {
                              "id": "FIRST_PHOTO_ID"
                          },
                          "pose": {
                              "latLngPair": {
                                  "latitude": 37.1701638,
                                  "longitude": -122.3624387
                              }
                          }
                      },
                      "updateMask": "pose.latLngPair"
                  },
                  {
                      "photo": {
                          "photoId": {
                              "id": "SECOND_PHOTO_ID"
                          },
                          "pose": {
                              "latLngPair": {
                                  "latitude": 37.1685704,
                                  "longitude": -122.3618021
                              }
                          }
                      },
                      "updateMask": "pose.latLngPair"
                  }
              ]
          }'
  

מחיקת תמונה

    $ curl --request DELETE \
    --url 'https://streetviewpublish.googleapis.com/v1/photo/PHOTO_ID?key=YOUR_API_KEY' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  

מה זה updateMask?

באמצעות updateMask, ניתן לצמצם את הבקשות אם רוצים לעדכן חלק של התמונה שלכם, במקום את כולה. בלי updateMask, הבקשה תעדכן את את כל התמונה. המשמעות היא שאם לא מגדירים את updateMask והבקשה שלך לא צוין pose, pose של התמונה שלך יימחק. כמה ערכים אפשריים עבור updateMask הם: places, pose.heading, pose.latlngpair, pose.level, connections. אפשר להוסיף לקובץ updateMask כמה ערכים שמופרדים בפסיקים.