Accedere a elementi multimediali

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, all'interno della raccolta di un utente.

Tieni presente che l'applicazione non deve memorizzare nella cache le foto o i video di un utente per lunghi periodi. ma, a seconda del caso d'uso, puoi archiviare o memorizza nella cache l'ID elemento multimediale per lungo come necessario. Devi inoltre tenere presente che l'accesso all'interfaccia utente dati sono regolati dalla privacy obblighi di sicurezza.

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 richiesto.

  • photoslibrary.readonly consente l'accesso a tutti gli elementi multimediali della biblioteca dell'utente
  • photoslibrary.readonly.appcreateddata consente l'accesso solo ai contenuti multimediali che sono stati creati dall'app

Elementi multimediali

R mediaItem rappresenta una rappresentazione di elementi multimediali, come una foto o un video, che sono stati caricati nella libreria 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 come visibile all'interno Google Foto.
baseUrl Utilizzato per accedere ai byte non elaborati. Per ulteriori informazioni, consulta la sezione URL di base.
productUrl

Un link all'immagine in Google Foto. Questo link non può essere aperti dallo sviluppatore, solo dall'utente. Gli URL indirizzano a un elemento multimediale in 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 per identificare più facilmente il tipo di elemento 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 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 photoslibrary.sharing ambito.

Contiene informazioni sul collaboratore che ha aggiunto questo elemento media. Per maggiori dettagli, vedi Condividere contenuti multimediali.

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. ContributorInfo contiene metadati per gli elementi di un album condiviso. Questo campo viene incluso solo se che elenca i contenuti di un album condiviso in cui l'utente ha concesso l'autorizzazione photoslibrary.sharing ambito di autorizzazione.

Se l'elemento multimediale è un video, il file video deve essere prima elaborato. La mediaItem contiene un campo status all'interno di mediaMetadata che descrive il stato di elaborazione del file video. Un file appena caricato restituisce videoProcessingStatus con il valore PROCESSING prima di essere READY per l'uso. baseUrl di un elemento multimediale video non è disponibile finché 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. Il video contiene 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 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 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
}

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

Ecco una richiesta GET che mostra l'accesso riuscito e non riuscito 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: accedi direttamente a una foto, a una miniatura di un video o scarica i byte di un video.
  • coverPhotoBaseUrl: accedi direttamente alla foto di copertina dell'album.
  • profilePictureBaseUrl: accedi direttamente alla foto del profilo del proprietario di un mediaItem.

URL di base delle immagini

Ecco l'elenco di opzioni che puoi utilizzare con gli URL per le immagini base:

Parametro
w, h

Descrizione

Larghezza, w e altezza, h parametri.

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 c di ritaglio.

Se vuoi ritagliare l'immagine in modo che abbia esattamente le dimensioni di larghezza e altezza che hai specificato, concatena l'URL di base con il parametro facoltativo -c e i parametri obbligatori w e h.

La dimensione (in pixel) deve essere compresa 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, d.

Se vuoi scaricare l'immagine mantenendo tutti i metadati Exif tranne i metadati sulla posizione, concatena l'URL di base con il parammetro d.

Esempi:

base-url=d

In questo esempio, l'applicazione scarica un'immagine contenente Metadati esclusi quelli sulla località:

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 mediaItem, concatena il baseUrl con il parametro dv per il download del 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 il download dei video possono richiedere alcuni secondi e restituire byte.

Prima di utilizzare questo parametro, controlla che il campo mediaMetadata.status degli elementi multimediali sia READY. In caso contrario, se l'elaborazione dell'elemento multimediale non è stata completata, potresti ricevere un messaggio di errore.

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 dell'immagine.

Per impostazione predefinita, tutte le miniature dei video includono l'overlay di una 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 no per rimuovere l'overlay della miniatura.

Se vuoi recuperare la miniatura di un video senza l'overlay di un pulsante di riproduzione, concatena l'URL di base con il segno no .

Il parametro no deve essere utilizzato con almeno uno dei seguenti valori: il parametri url di base dell'immagine.

Esempi:

base-url=wmax-width-hmax-height-no

L'esempio seguente mostra la miniatura di un video che ha esattamente 1280 px di larghezza per 720 px di altezza e non include un overlay di 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 URL di base delle immagini oppure URL di base dei video per le richieste baseUrl di foto in movimento.

Parametro
dv

Descrizione

Per recuperare l'elemento video di un elemento multimediale di una foto in movimento, utilizza il parametro dv come faresti per scaricare gli URL di base dei video.
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 di base delle immagini.