Dopo aver effettuato chiamate per elencare i contenuti di una raccolta fotografica o di un album, anziché archiviare gli elementi multimediali restituiti, l'applicazione dovrebbe archiviare gli ID degli elementi multimediali. Questo perché i contenuti degli elementi multimediali potrebbero 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.
Tieni presente che la tua applicazione non deve memorizzare nella cache la foto o il video di un utente per lunghi periodi di tempo ma, a seconda del caso d'uso, puoi archiviare o memorizzare nella cache l'ID elemento multimediale per tutto il tempo necessario. Tieni inoltre presente che l'accesso ai dati utente è regolato da obblighi in materia di privacy.
Ambiti di autorizzazione obbligatori
Per accedere agli elementi multimediali, l'app deve richiedere almeno uno dei seguenti ambiti di autorizzazione. L'accesso agli elementi multimediali restituiti nella risposta dipende dagli ambiti richiesti.
photoslibrary.readonlyconsente l'accesso a tutti gli elementi multimediali nella raccolta dell'utentephotoslibrary.readonly.appcreateddataconsente l'accesso solo agli elementi multimediali creati dall'app
Elementi multimediali
Una
mediaItem
è una rappresentazione di contenuti multimediali, ad esempio una foto o un video, che sono stati caricati nella
raccolta di Google Foto. Si tratta di un oggetto di primo livello e le sue proprietà
possono variare in base al tipo di elemento multimediale sottostante.
Nella tabella seguente sono elencate le proprietà mediaItem:
| Proprietà | |
|---|---|
id |
Un ID permanente e stabile utilizzato per identificare l'oggetto. |
description |
Descrizione dell'elemento multimediale visualizzata in Google Foto. |
baseUrl |
Utilizzato per accedere ai byte non elaborati. Per ulteriori informazioni, consulta la sezione 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 nella libreria. Se l'URL è stato recuperato da una ricerca di album, rimanda all'elemento all'interno dell'album. |
mimeType |
Il tipo di elemento multimediale che consente di identificare facilmente il tipo di contenuto multimediale
(ad esempio: image/jpg). |
filename |
Il nome del file dell'elemento multimediale mostrato all'utente nell'app Google Foto (nella sezione delle informazioni dell'elemento). |
mediaMetadata |
Varia a seconda del tipo di contenuti multimediali, ad esempio photo
o video.
Per ridurre il payload, è possibile utilizzare maschere di campo.
|
contributorInfo |
Questo campo viene compilato solo se l'elemento multimediale si trova in un album condiviso creato da questa app e l'utente ha concesso l'ambito Contiene informazioni sul collaboratore che ha aggiunto questo elemento multimediale. Per maggiori dettagli, vedi Condividere contenuti multimediali. |
Recupera un elemento multimediale
Per recuperare un elemento multimediale, chiama mediaItems.get utilizzando mediaItemId. La richiesta restituisce un singolo elemento multimediale.
L'elemento mediaItem contiene proprietà come l'ID, la descrizione e l'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. ContributorInfo contiene i metadati per gli elementi che fanno parte di un album condiviso. Questo campo viene incluso solo nell'elenco dei contenuti di un album condiviso in cui l'utente ha concesso l'photoslibrary.sharing
ambito di autorizzazione.
Se l'elemento multimediale è un video, il file video deve essere prima elaborato. L'elemento 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 sarà disponibile solo dopo che il video sarà 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 foto ha il seguente aspetto. La proprietà della foto contiene i metadati per gli 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 ha il seguente aspetto. 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"
}
}
Java
La proprietà della foto contiene i metadati per gli elementi fotografici.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasPhoto()) {
// This media item is a photo and has additional photo metadata
Photo photoMetadata = metadata.getPhoto();
String cameraMake = photoMetadata.getCameraMake();
String cameraModel = photoMetadata.getCameraModel();
float aperture = photoMetadata.getApertureFNumber();
int isoEquivalent = photoMetadata.getIsoEquivalent();
// ...
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
La proprietà video contiene i metadati per gli elementi video.
try {
// Get a media item using its ID
String mediaItemId = "...";
MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
// Get some properties from the retrieved media item
String id = item.getId();
String description = item.getDescription();
String baseUrl = item.getBaseUrl();
String productUrl = item.getProductUrl();
// ...
if (item.hasMediaMetadata()) {
// The media item contains additional metadata, such as the height and width
MediaMetadata metadata = item.getMediaMetadata();
long height = metadata.getHeight();
long width = metadata.getWidth();
Timestamp creationTime = metadata.getCreationTime();
// ...
if (metadata.hasVideo()) {
// This media item is a video and has additional video metadata
Video videoMetadata = metadata.getVideo();
VideoProcessingStatus status = videoMetadata.getStatus();
if (status.equals(VideoProcessingStatus.READY)) {
// This video media item has been processed
String cameraMake = videoMetadata.getCameraMake();
String cameraModel = videoMetadata.getCameraModel();
double fps = videoMetadata.getFps();
// ...
}
}
}
if (item.hasContributorInfo()) {
// A user has contributed this media item to a shared album
ContributorInfo contributorInfo = item.getContributorInfo();
String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
String displayName = contributorInfo.getDisplayName();
}
} catch (ApiException e) {
// Handle error
}
PHP
La proprietà della foto contiene i metadati per gli elementi fotografici.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$photoMetadata = $metadata->getPhoto();
if (!is_null($photoMetadata)) {
// This media item is a photo and has additional photo metadata
$cameraMake = $photoMetadata->getCameraMake();
$cameraModel = $photoMetadata->getCameraModel();
$aperture = $photoMetadata->getApertureFNumber();
$isoEquivalent = $photoMetadata->getIsoEquivalent();
// ...
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
La proprietà video contiene i metadati per gli elementi video.
try {
// Get a media item using its ID
$mediaItemId = "...";
$item = $photosLibraryClient->getMediaItem($mediaItemId);
// Get some properties from the retrieved media item
$id = $item->getId();
$description = $item->getDescription();
$baseUrl = $item->getBaseUrl();
$productUrl = $item->getProductUrl();
// ...
$metadata = $item->getMediaMetadata();
if (!is_null($metadata)) {
// The media item contains additional metadata, such as the height and width
$height = $metadata->getHeight();
$width = $metadata->getWidth();
$creationTime = $metadata->getCreationTime();
// ...
$videoMetadata = $metadata->getVideo();
if (!is_null($videoMetadata)) {
// This media item is a video and has additional video metadata
if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
// This video media item has been processed
$cameraMake = $videoMetadata->getCameraMake();
$cameraModel = $videoMetadata->getCameraModel();
$fps = $videoMetadata->getFps();
// ...
}
}
}
$contributorInfo = $item->getContributorInfo();
if (!is_null($contributorInfo)) {
// A user has contributed this media item to a shared album
$profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
$displayName = $contributorInfo->getDisplayName();
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
Visualizza più elementi multimediali
Per recuperare più elementi multimediali in base ai relativi identificatori, chiama
mediaItems.batchGet
utilizzando i mediaItemId.
La richiesta restituisce un elenco di MediaItemResults nell'ordine degli identificatori degli elementi multimediali forniti nella richiesta. Ogni risultato contiene un elemento MediaItem o Status in caso di errore.
Il numero massimo di elementi multimediali che puoi richiedere in una chiamata è 50. L'elenco degli elementi multimediali non deve contenere identificatori duplicati e non può essere vuoto.
REST
Ecco una richiesta GET che mostra l'accesso riuscito e non riuscito agli elementi multimediali. Specifica ogni identificatore dell'elemento multimediale come nuovo
parametro di query mediaItemIds nell'ambito 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."
}
}
]
}
Java
try {
// List of media item IDs to retrieve
List<String> mediaItemIds = Arrays
.asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");
// Get a list of media items using their IDs
BatchGetMediaItemsResponse response = photosLibraryClient
.batchGetMediaItems(mediaItemIds);
// Loop over each result
for (MediaItemResult result : response.getMediaItemResultsList()) {
// Each MediaItemresult contains a status and a media item
if (result.hasMediaItem()) {
// The media item was successfully retrieved, get some properties
MediaItem item = result.getMediaItem();
String id = item.getId();
// ...
} else {
// If the media item is not set, an error occurred and the item could not be loaded
// Check the status and handle the error
Status status = result.getStatus();
// ...
}
}
} catch (ApiException e) {
// Handle error
}
PHP
try {
// List of media item IDs to retrieve
$mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];
// Get a list of media items using their IDs
$response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);
// Loop over each result
foreach ($response->getMediaItemResults() as $itemResult) {
// Each MediaItemresult contains a status and a media item
$mediaItem = $itemResult->getMediaItem();
if(!is_null($mediaItem)){
// The media item was successfully retrieved, get some properties
$id = $mediaItem->getId();
// ...
} else {
// If the media item is null, an error occurred and the item could not be loaded
}
}
} catch (\Google\ApiCore\ApiException $e) {
// Handle error
}
URL di base
Gli URL di base all'interno dell'API della libreria di Google Foto ti consentono di accedere ai byte degli elementi multimediali. Utilizzando i vari URL di base, l'app può scaricare gli elementi multimediali o visualizzare gli elementi multimediali all'interno dell'app. Gli URL di base sono stringhe incluse nella risposta quando elenchi album o accedi a elementi multimediali. Sono validi per 60 minuti e richiedono parametri aggiuntivi in quanto non possono essere utilizzati così come sono.
I vari URL di base sono:
baseUrl: accedi direttamente alla foto e alla miniatura di un video oppure scarica i byte del video.coverPhotoBaseUrl: accedi direttamente alla foto di copertina dell'album.profilePictureBaseUrl: accedi direttamente alla foto del profilo del proprietario di unmediaItem.
URL di base immagine
Di seguito è riportato un elenco di opzioni che puoi utilizzare con gli URL di base delle immagini:
| Parametro | |
|---|---|
w, h |
Descrizione I parametri di larghezza, Per accedere all'elemento multimediale di un'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 adattata a 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 mostrare un elemento multimediale con una dimensione massima di 2048 px e non più alta di 1024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descrizione Parametro di ritaglio Se vuoi ritagliare l'immagine nelle dimensioni esatte di larghezza e altezza specificate, 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 superano le dimensioni richieste, l'immagine viene ridimensionata e ritagliata (mantenendo le proporzioni). Esempi: base-url=wmax-width-hmax-height-c In questo esempio, l'applicazione visualizza un elemento multimediale di esattamente 256 px di larghezza per 256 px di altezza, come una miniatura: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Descrizione Il parametro di download Se vuoi scaricare l'immagine che conserva tutti i metadati Exif tranne i metadati della 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, ad eccezione dei metadati sulla posizione: https://lh3.googleusercontent.com/p/Az....XabC=d |
URL di base del video
Ecco l'elenco di 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 dei video possono richiedere alcuni secondi per restituire i byte. Prima di utilizzare questo parametro, verifica 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 url di base delle immagini. Per impostazione predefinita, tutte le miniature dei video includono un overlay di un pulsante di riproduzione. Controlla il parametro -no per rimuovere questo overlay. Esempi: Per alcuni esempi, consulta la tabella degli URL di base delle immagini. |
no |
Descrizione Rimuovi overlay miniatura, 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 di base dell'immagine. Esempi: base-url=wmax-width-hmax-height-no L'esempio seguente mostra una miniatura di un video di esattamente 1280 px di larghezza per 720 px di altezza e non include un overlay di pulsanti di riproduzione: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
URL di base per le foto in movimento
Le foto in movimento contengono elementi foto e video. Puoi utilizzare i parametri degli
URL di base immagine o degli
URL di base del video per le richieste baseUrl delle foto in movimento.
| Parametro | |
|---|---|
dv |
Descrizione Per recuperare l'elemento video di un elemento multimediale relativo a una foto in movimento, usa il parametro |
w, h, c e
d |
Descrizione Per recuperare l'elemento fotografico di un elemento multimediale relativo a una foto in movimento, utilizza il formato per gli URL di base immagine. |