Effettuare le prime chiamate API

Per completare i passaggi necessari per effettuare chiamate di base all'API Street View Publish, segui la procedura illustrata in questo tutorial.

Effettuare chiamate HTTP

Puoi chiamare l'API Street View Publish utilizzando più strumenti come curl, wget e Postman. Nella maggior parte dei casi è consigliabile utilizzare un linguaggio di programmazione a tua scelta per creare un'applicazione client che utilizzi l'API, ma questo tutorial ti guiderà nelle nozioni di base guidando i singoli comandi.

Forniamo anche alcune librerie client se non volete effettuare chiamate HTTP dirette.

Prerequisiti

1. Per accedere alla Console API di Google, richiedere una chiave API e registrare la tua applicazione, devi avere un Account Google.

2. Crea un progetto in Google Developers Console e ottieni le credenziali di autorizzazione affinché la tua applicazione possa inviare richieste API.

3. Dopo aver creato il progetto, assicurati che l'API Street View Publish sia uno dei servizi registrati dall'applicazione:

   1. Vai alla Console API e seleziona il progetto appena registrato.
   2. Visita la pagina relativa all'API abilitata. Assicurati che l'API Google Street View sia presente nell'elenco delle API abilitate. In caso contrario, apri la libreria delle API e attiva l'API.

4. Leggi la guida all'autenticazione per informazioni su come implementare l'autorizzazione OAuth 2.0.

5. Acquisisci familiarità con i concetti principali del formato dati JSON (JavaScript Object Notation). JSON è un formato dati comune indipendente dal linguaggio che fornisce una semplice rappresentazione testuale di strutture di dati arbitrari. Per ulteriori informazioni, visita il sito json.org.

Ottenere una chiave API

Ai fini dell'autenticazione e della quota, dovrai utilizzare l'API Google Street View Publish con le credenziali generate da Developers Console.

1. Vai alla pagina Credenziali in Developers Console.
2. Se disponi già di una chiave API, puoi utilizzare il relativo valore. Altrimenti, creane una nuova selezionando Chiave API dal menu Nuove credenziali.

Ottenere un token di accesso

1. Vai a Google Developers OAuth 2.0 Playground.
2. Fai clic sul menu delle impostazioni (l'icona a forma di ingranaggio in alto a destra), seleziona Utilizza le tue credenziali OAuth e inserisci Client ID e Client secret nei campi corrispondenti, quindi fai clic su Chiudi.
   Per ottenere l'ID client e il client secret, vai alla pagina Credenziali in Developers Console. Se non hai un client OAuth 2.0 esistente, crea un nuovo ID client OAuth 2.0 selezionando ID client OAuth nel menu Crea credenziali e utilizza la seguente configurazione:

   Campo	Valore
   Tipo di applicazione	Applicazione web
   Nome	(qualsiasi valore)
   Limitazioni: origini JavaScript autorizzate	(vuota)
   Limitazioni: URI di reindirizzamento autorizzati	https://developers.google.com/oauthplayground

   
   Fai clic su crea. L'ID client e il client secret ti verranno forniti.
3. In Passaggio 1: seleziona &autorizza le API, inserisci l'ambito dell'API https://www.googleapis.com/auth/streetviewpublish nel campo Inserisci i tuoi ambiti, quindi fai clic su Autorizza API. Si aprirà una nuova pagina per confermare che vuoi autorizzare l'API.
4. Fai clic su Codice di autorizzazione di Exchange per i token. Il campo del token di accesso verrà compilato nel campo che conterrà il token di accesso da utilizzare nel passaggio successivo. Il token di accesso scade dopo 60 minuti. Puoi selezionare l'opzione per aggiornare automaticamente il token prima che scada, in modo da crearne uno nuovo.

Invia una richiesta HTTP

Dopo aver ottenuto la chiave API e il token di accesso, puoi eseguire il comando seguente su una shell per eseguire una chiamata HTTP al servizio. Nell'esempio riportato di seguito, effettuiamo una chiamata al metodo /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'
  

Richieste di esempio

Una volta acquisita maggiore dimestichezza con l'invio della richiesta HTTP precedente, prova ad adottare altri metodi. Di seguito sono riportate varie chiamate.

Ricevere un elenco delle tue foto

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

Recupero di una foto

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

Caricamento di una foto

Per creare una foto sono richieste tre chiamate separate. La prima chiamata restituirà un URL di caricamento, che viene utilizzato nella seconda chiamata per caricare i byte di foto. Una volta caricati i byte della foto, la terza chiamata carica i metadati della foto e restituisce l'ID della foto.

Attenzione: leggi i criteri di accettazione della pubblicazione prima di pubblicare una foto. Per poter essere pubblicate, le foto devono anche avere i metadati descritti in Metadati XMP di foto sferiche.

1. Richiedi un URL di caricamento

           $ 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. Carica le foto in byte nell'URL di caricamento

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

3. Carica i metadati della foto

           $ 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
                     },
                   }'
         

Aggiornamento di una foto

   $ 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
                 }
               }
             }'
  

Aggiornamento di più foto in gruppo

   $ 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"
                  }
              ]
          }'
  

Eliminare una foto

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

Cos'è updateMask?

updateMask è un modo per mantenere piccole le richieste se vuoi aggiornare parte della foto anziché tutte. Senza updateMask, la richiesta aggiornerà l'intera foto. Ciò significa che se non imposti updateMask e manca la tua richiesta per pose, la foto pose verrà cancellata. Alcuni valori possibili per updateMask sono: places, pose.heading, pose.latlngpair, pose.level, connections. Puoi inserire più valori delimitati da virgole in updateMask.