如要完成對 Street View Publish API 基本呼叫所需的步驟,請按照本教學課程的步驟操作。
發出 HTTP 呼叫
您可以透過多種工具 (例如 curl、wget 和 Postman) 呼叫 Street View Publish API。在大部分情況下,建議您使用您偏好的程式設計語言建構使用 API 的用戶端應用程式,但本教學課程將引導您完成個別指令的基本概念。
如果您不想要直接呼叫 HTTP,我們也會提供一些用戶端程式庫。
必要條件
-
您必須擁有 Google 帳戶,才能存取 Google API 控制台、要求 API 金鑰,以及註冊應用程式。
-
在 Google Developers Console 中建立專案並取得授權憑證,方便應用程式提交 API 要求。
-
建立專案後,請確認 Street View Publish API 是應用程式註冊使用的服務之一:
- 前往 API 控制台,然後選取剛註冊的專案。
- 前往「已啟用的 API」頁面。確認 Google Street View API 已顯示在已啟用的 API 清單中。如果沒有,請開啟 API 程式庫並啟用 API。
-
請參閱驗證指南,瞭解如何導入 OAuth 2.0 授權。
-
熟悉 JavaScript Object Notation (JSON) 資料格式的核心概念。JSON 是一種與語言無關的通用資料格式,可透過簡單的文字表示任意資料結構。詳情請參閱 json.org 網站。
取得 API 金鑰
為進行驗證及配額,您必須使用 Google Developers View Publish API,以及透過 Developers Console 產生的憑證。
取得存取權杖
- 前往 Google Developers OAuth 2.0 Playground。
- 按一下設定選單 (即右上方的齒輪圖示),然後勾選「Use your own OAuth credentials」,然後在對應的欄位中輸入「
Client ID
」和「Client secret
」,然後按一下「Close」。 - 在「步驟 1:選取並授權 API」下方,在「輸入您自己的範圍」欄位中輸入 API 範圍
https://www.googleapis.com/auth/streetviewpublish
,然後按一下「Authorize API」。系統隨即會開啟新頁面,確認您要授權 API。 - 按一下 [Exchange 權杖授權]。系統會填入「存取權杖」欄位,其中包含您在下一個步驟中使用的存取權杖。存取權杖會在 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'
上傳相片
建立相片需要三個獨立的通話。第一次呼叫會傳回上傳網址,在第二個呼叫中用於上傳相片位元組。相片位元組上傳之後,第三次呼叫會上傳相片的中繼資料,並傳回相片 ID。
- 要求上傳網址
$ 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'
- 將相片位元組上傳到上傳網址
$ curl --request POST \ --url 'UPLOAD_URL' \ --upload-file 'PATH_TO_FILE' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
- 上傳相片的中繼資料
$ 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'
什麼是 update 遮罩?
如果想更新部分相片,而非要求所有相片,使用 updateMask
可以讓要求保持精簡。如果沒有 updateMask
,你的要求會更新整張相片。這表示如果你沒有設定 updateMask
,且你的要求缺少 pose
,系統會清除你的相片的 pose
。以下為 updateMask
的一些可能值:places, pose.heading, pose.latlngpair, pose.level,
connections
。您可以在 updateMask
中加入多個以半形逗號分隔的值。