Una volta che un utente ha configurato il proprio dispositivo Ambient e selezionato le origini multimediali in Google Foto, la tua applicazione può elencare e recuperare questi elementi multimediali da visualizzare.
Prima di iniziare
- Controlla la configurazione del dispositivo:assicurati di aver creato e configurato un dispositivo per l'utente.
- Comprendere il flusso dell'API Ambient:esamina il
flusso dell'API Ambient per comprendere la
procedura generale, in particolare il passaggio che prevede il polling per
mediaSourcesSet.
Sondaggio per mediaSourcesSet
Prima di poter elencare gli elementi multimediali per un dispositivo, l'utente deve aver selezionato le foto che vuole condividere con la tua applicazione all'interno dell'app Google Foto. La tua applicazione deve eseguire il polling del dispositivo per determinare quando è stata effettuata questa selezione.
Chiama periodicamente il metodo devices.get per deviceId specifico. Monitora il campo mediaSourcesSet nella
risposta AmbientDevice. Inizialmente sarà false. Una volta che l'utente ha
selezionato correttamente le origini media, questo campo cambierà in true.
La risposta AmbientDevice include un pollingConfig con un pollInterval
che devi utilizzare come linea guida per la frequenza di polling.
Elenca elementi multimediali
Una volta che mediaSourcesSet è true per un dispositivo, puoi iniziare a recuperare gli elementi multimediali
selezionati dall'utente.
Utilizza l'endpoint
mediaItems.list: invia una richiesta GET ahttps://photosambient.googleapis.com/v1/mediaItems, fornendodeviceIdnel percorso.Gestisci la paginazione (se necessario): la risposta potrebbe essere paginata. Utilizza il parametro
pageSizeper specificare il numero massimo di elementi da restituire e il parametropageTokendi una risposta precedente per recuperare le pagine successive di risultati.Elabora gli elementi multimediali:la risposta conterrà un array di oggetti
AmbientMediaItem, ognuno dei quali rappresenta un elemento multimediale selezionato. Questi oggetti includono dettagli essenziali come:id: l'identificatore univoco dell'elemento multimediale.creationTime: il timestamp della creazione dell'elemento multimediale.mediaFile: un oggetto contenente i dettagli per accedere ai contenuti effettivi.
Il campo mediaFile include baseUrl. Questo baseUrl è ciò che utilizzerai per creare URL per accedere ai contenuti dell'elemento multimediale in varie risoluzioni o formati.
URL di base
Gli URL di base nelle API di Google Foto forniscono l'accesso ai byte non elaborati degli elementi multimediali, consentendo alla tua app di scaricarli o visualizzarli. Questi URL sono inclusi nelle risposte quando vengono elencati gli album (API Library) o quando si accede agli elementi multimediali (API Library e Picker). Ricorda che gli URL di base richiedono parametri aggiuntivi per funzionare correttamente.
Per l'API Picker:
Tutti gli oggetti PickedMediaItem.mediaFile includono un baseUrl.
Gli URL di base rimangono attivi per 60 minuti, ma possono scadere prima se l'utente revoca le autorizzazioni della tua app tramite le impostazioni del suo Account Google.
Per l'API Library:
Gli URL di base rimangono attivi per 60 minuti.
I vari URL di base sono:
baseUrl: accedi direttamente alla foto, alla miniatura di un video o scarica i byte del video.coverPhotoBaseUrl: accedi direttamente alla copertina dell'album.profilePictureBaseUrl: Accedi direttamente alla foto del profilo del proprietario di unmediaItem.
URL di base delle immagini
Di seguito è riportato l'elenco delle opzioni che puoi utilizzare con gli URL di base delle immagini:
| Parametro | |
|---|---|
w, h |
Descrizione I parametri larghezza, Per accedere a un elemento multimediale immagine, ad esempio una foto o una miniatura di un video, devi specificare le dimensioni che prevedi di visualizzare nella tua applicazione (in modo che l'immagine possa essere scalata in queste dimensioni mantenendo le proporzioni). Per farlo, concatena l'URL di base con le dimensioni richieste, come mostrato negli esempi. Esempi: base-url=wmax-width-hmax-height Ecco un esempio per visualizzare un elemento multimediale non più largo di 2048 px e non più alto di 1024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descrizione Il parametro di ritaglio Se vuoi ritagliare l'immagine in base alle dimensioni esatte di larghezza e altezza
che hai specificato, concatena l'URL di base con il
parametro facoltativo Le dimensioni (in pixel) devono essere comprese nell'intervallo [1, 16383]. Se la larghezza o l'altezza dell'immagine supera la dimensione richiesta, l'immagine viene ridimensionata e ritagliata (mantenendo le proporzioni). Esempi: base-url=wmax-width-hmax-height-c In questo esempio, l'applicazione mostra un elemento multimediale di 256 px di larghezza per 256 px di altezza, ad esempio una miniatura: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Descrizione Il parametro download, Se vuoi scaricare l'immagine conservando tutti i metadati Exif
tranne i metadati sulla posizione, concatena l'URL di base con il
parametro Esempi: base-url=d In questo esempio, l'applicazione scarica un'immagine con tutti i metadati tranne quelli della posizione: https://lh3.googleusercontent.com/p/Az....XabC=d |
URL di base dei video
Ecco l'elenco delle opzioni che puoi utilizzare con gli URL di base dei video:
| Parametro | |
|---|---|
dv |
Descrizione Per accedere ai byte di un video Il parametro dv richiede una versione transcodificata di alta qualità del video originale. Il parametro non è compatibile con i parametri w e h. Gli URL di base per i download di video possono richiedere fino a qualche secondo per restituire i byte. Prima di utilizzare questo parametro, verifica che il campo Esempi: base-url=dv Il seguente esempio mostra come scaricare i byte di un video: https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w, h, c e
d |
Descrizione Per accedere alla miniatura del video, utilizza uno dei parametri dell'URL di base dell'immagine. Per impostazione predefinita, tutte le miniature dei video includono un overlay di un pulsante di riproduzione. Consulta il parametro -no per rimuovere questa sovrapposizione. Esempi: Per esempi, consulta la tabella degli URL di base delle immagini. |
no |
Descrizione Il parametro Se vuoi recuperare la miniatura di un video senza la sovrapposizione di un pulsante di riproduzione, concatena l'URL di base con il parametro no. Il parametro no deve essere utilizzato con almeno uno dei parametri URL di base dell'immagine. Esempi: base-url=wmax-width-hmax-height-no L'esempio seguente mostra una miniatura video di 1280 px di larghezza per 720 px di altezza e non include una sovrapposizione del pulsante di riproduzione: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URL di base delle foto in movimento
Le foto in movimento contengono elementi sia fotografici che video. Puoi utilizzare i parametri degli URL di base delle immagini o degli URL di base dei video per le richieste di foto in movimento baseUrl.
| Parametro | |
|---|---|
dv |
Descrizione Per recuperare l'elemento video di un elemento multimediale di una foto in movimento, utilizza
il parametro |
w, h, c e
d |
Descrizione Per recuperare l'elemento fotografico di un elemento multimediale di una foto in movimento, utilizza il formato per gli URL di base delle immagini. |
Norme per i contenuti e filtri
Google Foto applica per impostazione predefinita il filtro dei contenuti standard per le immagini e i video visualizzati su un dispositivo condiviso, ad esempio una TV o un display digitale. Questo filtro è progettato per ottimizzare l'esperienza di visualizzazione escludendo contenuti come:
- Immagini funzionali (ad es. screenshot, documenti, ricevute).
- Immagini che potrebbero essere visualizzate male su uno schermo di grandi dimensioni (ad es. risoluzione molto bassa, sfocatura, grana eccessiva).
- Contenuti identificati come altamente personali o sensibili, che potrebbero non essere destinati alla visualizzazione generale in un ambiente condiviso.
Il filtraggio dei contenuti è automatizzato. Per dare agli utenti un maggiore controllo sui contenuti visualizzati, puoi consentire loro di selezionare e aggiornare manualmente le fonti multimediali utilizzate per il display sempre attivo.
Passaggi successivi
- Applicazione di esempio: la nostra applicazione di esempio
include un esempio di elenco e recupero di elementi multimediali. Per saperne di più, consulta le funzioni
checkMediaSourcesSetefetch_media_item_list. - Documentazione di riferimento:consulta la documentazione di riferimento completa sugli elementi multimediali per informazioni dettagliate su tutti i metodi disponibili, sui parametri di richiesta e risposta e sui codici di errore.