Dopo aver effettuato chiamate per elencare i contenuti di una raccolta di foto o di un album, anziché memorizzare gli elementi multimediali restituiti, l'applicazione deve memorizzare gli ID degli elementi multimediali. Questo accade perché i contenuti degli elementi multimediali possono cambiare e dopo un determinato periodo di tempo gli URL inclusi nella risposta scadono. L'ID elemento multimediale identifica in modo univoco un elemento multimediale, ad esempio una foto o un video all'interno della raccolta di un utente.
Ambiti di autorizzazione richiesti
L'accesso agli elementi multimediali creati dall'app richiede
l'ambito photoslibrary.readonly.appcreateddata. Per ulteriori informazioni sugli ambiti, consulta Ambiti di autorizzazione.
Elementi multimediali
Un elemento mediaItem
è una rappresentazione di elementi multimediali, come una foto o un video, che è stato caricato
nella raccolta di Google Foto. Si tratta di un oggetto di primo livello e le sue proprietà possono essere diverse in base al tipo di media sottostante.
La tabella seguente elenca le proprietà mediaItem:
| Proprietà | |
|---|---|
id |
Un ID permanente e stabile utilizzato per identificare l'oggetto. |
description |
Descrizione dell'elemento multimediale visibile in Google Foto. |
baseUrl |
Utilizzato per accedere ai byte non elaborati. Per ulteriori informazioni, consulta URL di base. |
productUrl |
Un link all'immagine all'interno di Google Foto. Questo link non può essere aperto dallo sviluppatore, ma solo dall'utente. Gli URL rimandano a un elemento multimediale della raccolta. Se l'URL è stato recuperato da una ricerca di album, rimanda all'elemento all'interno dell'album. |
mimeType |
Il tipo di elemento multimediale per identificare facilmente il tipo di media
(ad es. image/jpg). |
filename |
Il nome file dell'elemento multimediale mostrato all'utente nell'app Google Foto (nella sezione delle informazioni dell'elemento). |
mediaMetadata |
Varia a seconda del tipo di media sottostante, ad esempio photo
o video.
Per ridurre il payload, è possibile utilizzare le maschere di campo.
|
Recuperare un elemento multimediale
Per recuperare un elemento multimediale, chiama
mediaItems.get utilizzando
mediaItemId. La richiesta restituisce un singolo elemento multimediale.
mediaItem contiene proprietà, come ID, descrizione e URL. Le
informazioni aggiuntive all'interno di photo o video si basano sui metadati
all'interno del file. Non tutte le proprietà potrebbero essere presenti.
Se l'elemento multimediale è un video, il file video deve essere elaborato per primo. mediaItem contiene un campo status all'interno di mediaMetadata che descrive lo stato di elaborazione del file video. Un file appena caricato restituisce videoProcessingStatus con il valore PROCESSING prima che sia READY per l'utilizzo. L'elemento baseUrl
di un elemento multimediale video non sarà disponibile fino a quando il video non è stato elaborato.
REST
Ecco una richiesta GET:
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
La risposta per un elemento multimediale di tipo foto è simile alla seguente. La proprietà photo contiene i metadati degli elementi di foto.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"photo": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"focalLength": "focal-length-of-the-camera-lens",
"apertureFNumber": "aperture-f-number-of-the-camera-lens",
"isoEquivalent": "iso-of-the-camera",
"exposureTime": "exposure-time-of-the-camera-aperture"
}
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
La risposta per un elemento multimediale video è simile a questa. La proprietà video contiene i metadati per gli elementi video.
{
"id": "media-item-id",
"description": "item-description",
"productUrl": "url-to-open-in-google-photos",
"baseUrl": "base-url_do-not-use-directly",
"mimeType": "mime-type-of-media",
"filename": "item-filename",
"mediaMetadata": {
"width": "media-item-width",
"height": "media-item-height",
"creationTime": "media-item-creation-time",
"video": {
"cameraMake": "make-of-the-camera",
"cameraModel": "model-of-the-camera",
"fps": "frame-rate-of-the-video",
"status": "READY"
},
},
"contributorInfo": {
"profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
"displayName": "name-of-user"
}
}
Recupera più elementi multimediali
Per recuperare più elementi multimediali in base ai relativi identificatori, chiama
mediaItems.batchGet
utilizzando gli mediaItemId.
La richiesta restituisce un elenco di
MediaItemResults
nell'ordine degli identificatori degli elementi multimediali forniti nella richiesta. Ogni risultato contiene un MediaItem o un Status se si è verificato un errore.
Il numero massimo di elementi multimediali che puoi richiedere in una chiamata è 50. L'elenco di elementi multimediali non deve contenere identificatori duplicati e non può essere vuoto.
REST
Di seguito è riportata una richiesta GET che mostra l'accesso riuscito e non riuscito agli elementi multimediali. Specifica ogni identificatore di elemento multimediale come nuovo
parametro di query mediaItemIds all'interno della richiesta:
GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id Content-type: application/json Authorization: Bearer oauth2-token
La richiesta GET restituisce la seguente risposta:
{
"mediaItemResults": [
{
"mediaItem": {
"id": "media-item-id",
...
}
},
{
"mediaItem": {
"id": "another-media-item-id",
...
}
},
{
"status": {
"code": 3,
"message": "Invalid media item ID."
}
}
]
}
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 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 e alla miniatura di un video o scarica i byte di video.coverPhotoBaseUrl: accedi direttamente alla foto di 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 ridimensionata in queste dimensioni mantenendo le proporzioni). Per farlo, concatena l'URL 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 esatti 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 le dimensioni richieste, l'immagine viene ridotta e ritagliata (mantenendo le proporzioni). Esempi: base-url=wmax-width-hmax-height-c In questo esempio, l'applicazione mostra un elemento multimediale di esattamente 256 x 256 px, 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, ad eccezione dei 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 i metadati sulla posizione: https://lh3.googleusercontent.com/p/Az....XabC=d |
URL di base dei video
Di seguito è riportato 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. Per gli URL di base per i download dei video, il ritorno dei byte può richiedere fino a qualche secondo. Prima di utilizzare questo parametro, controlla che il campo Esempi: base-url=dv L'esempio seguente 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 con un pulsante di riproduzione. Controlla il parametro -no per rimuovere questo overlay. 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 l'overlay 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 immagine di base. Esempi: base-url=wmax-width-hmax-height-no L'esempio seguente mostra una miniatura di un video che ha esattamente 1280 px di larghezza e 720 px di altezza e non include un overlay 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 di foto di un elemento multimediale di foto in movimento, utilizza il formato per gli URL base delle immagini. |