اولین تماس های API خود را انجام دهید

برقراری تماس های HTTP

Street View Publish API را می توان با استفاده از چندین ابزار مانند curl، wget و Postman فراخوانی کرد. در بیشتر موارد، شما می خواهید از یک زبان برنامه نویسی انتخابی خود برای ساختن یک برنامه کلاینت استفاده کنید که از API استفاده می کند، اما این آموزش با راهنمایی شما از طریق دستورات فردی، شما را با اصول اولیه راهنمایی می کند.

همچنین اگر نمی‌خواهید تماس مستقیم HTTP برقرار کنید، تعدادی کتابخانه مشتری نیز ارائه می‌کنیم.

پیش نیازها

1. برای دسترسی به Google API Console، درخواست کلید API و ثبت برنامه خود به یک حساب Google نیاز دارید.

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. با مفاهیم اصلی فرمت داده های نشانه گذاری شی جاوا اسکریپت (JSON) آشنا شوید. JSON یک فرمت داده رایج و مستقل از زبان است که نمایش متنی ساده ای از ساختارهای داده دلخواه را ارائه می دهد. برای اطلاعات بیشتر، به json.org مراجعه کنید.

یک کلید API دریافت کنید

برای احراز هویت و اهداف سهمیه، باید از Google Street View Publish API با اعتبارنامه‌های تولید شده از Developers Console خود استفاده کنید.

1. به صفحه اعتبارنامه در Developers Console خود بروید.
2. اگر از قبل یک کلید API دارید، می توانید از مقدار آن استفاده کنید. در غیر این صورت، با انتخاب کلید API از منوی New credentials یک کلید جدید ایجاد کنید.

یک نشانه دسترسی دریافت کنید

1. به Google Developers OAuth 2.0 Playground بروید.
2. روی منوی تنظیمات (نماد چرخ دنده در بالا سمت راست) کلیک کنید، گزینه Use your own OAuth credentials را علامت بزنید و Client ID و Client secret خود را در فیلدهای مربوطه وارد کنید و سپس روی Close کلیک کنید.
3. در مرحله 1: APIها را انتخاب و تأیید کنید ، دامنه API https://www.googleapis.com/auth/streetviewpublish را در قسمت Input your own scopes وارد کنید، سپس روی Authorize APIs کلیک کنید. صفحه جدیدی باز می شود تا تأیید کند که می خواهید API را مجاز کنید.
4. روی کد مجوز تبادل برای توکن‌ها کلیک کنید. با این کار فیلد Access Token پر می شود که حاوی رمز دسترسی شما برای استفاده در مرحله بعدی است. رمز دسترسی 60 دقیقه دیگر منقضی می شود. شما می توانید گزینه رفرش خودکار توکن را قبل از انقضا انتخاب کنید که یک توکن جدید ایجاد می کند.

یک درخواست HTTP ارسال کنید

پس از اینکه کلید API و نشانه دسترسی خود را دریافت کردید، می‌توانید دستور زیر را بر روی پوسته اجرا کنید تا یک تماس HTTP با سرویس انجام دهید. در مثال زیر با متد /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 قرار دهید.