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 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 nella raccolta di un utente.
Tieni presente che la tua applicazione non deve memorizzare nella cache la foto o il video di un utente per periodi di tempo prolungati, ma, a seconda del caso d'uso, puoi memorizzare o memorizzare nella cache l'ID elemento multimediale per il tempo necessario. Tieni inoltre presente che l'accesso ai dati dell'utente è regolato da obblighi di privacy.
Ambiti di autorizzazione richiesti
Per accedere agli elementi multimediali, la tua app deve richiedere almeno uno dei seguenti ambiti di autorizzazione. L'accesso agli elementi multimediali restituiti nella risposta dipende dagli ambiti che hai richiesto.
photoslibrary.readonlyconsente l'accesso a tutti gli elementi multimediali della biblioteca dell'utentephotoslibrary.readonly.appcreateddataconsente l'accesso solo ai contenuti multimediali che sono stati creati dall'app
Elementi multimediali
Un 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 differire 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 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 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 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 media sottostante, ad esempio photo
o video.
Per ridurre il payload, è possibile utilizzare le 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. |
Ottieni 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. ContributorInfo contiene i metadati
per gli elementi che fanno parte di un album condiviso. Questo campo viene incluso solo quando
vengono elencati i 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 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 della foto è simile a questa. 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 degli 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 degli 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 degli 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
}
Recuperare 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."
}
}
]
}
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 Raccolta di Google Foto ti consentono di accedere ai byte degli elementi multimediali. Utilizzando i vari URL di base, la tua app può scaricare gli elementi multimediali o visualizzarli al suo interno. Gli URL di base sono stringhe incluse nella risposta quando elenchi gli album o accedi agli 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: consente di accedere direttamente a una foto, alla miniatura di un video o di scaricare i byte di un 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 di larghezza non superiore a 2048 px e non superiore a 1024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descrizione Parametro Se vuoi ritagliare l'immagine in base alle 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 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 mantenendo tutti i metadati Exif
tranne i metadati sulla posizione, concatena l'URL di base con il
parammetro 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 URL immagine di base. Per impostazione predefinita, tutte le miniature dei video includono un overlay con un pulsante di riproduzione. Consulta 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 di base dell'immagine. 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. |