Accedere a elementi multimediali

Dopo aver effettuato chiamate a elencare i contenuti di una raccolta fotografica o di un album, invece di archiviare gli elementi multimediali restituiti, l'applicazione dovrebbe archiviare ID degli elementi multimediali. Questo perché i contenuti degli elementi multimediali potrebbero modifichiamo e, dopo un certo periodo di tempo, gli URL inclusi nella risposta scadono. La L'ID elemento multimediale identifica in modo univoco un elemento multimediale, come 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 obbligatori

Per accedere agli elementi multimediali, la tua app deve richiedere almeno uno dei seguenti elementi 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 nella cartella libreria
  • photoslibrary.readonly.appcreateddata consente l'accesso solo agli elementi 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 variano 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 dell'album.

mimeType Il tipo di elemento multimediale per identificare facilmente il tipo di elemento multimediale. (ad esempio: image/jpg).
filename Il nome file dell'elemento multimediale mostrato all'utente in Google Foto (nella sezione delle informazioni sull'articolo).
mediaMetadata Varia a seconda del tipo di contenuto multimediale 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 questi contenuti multimediali molto utile. Per maggiori dettagli, vedi Condividere contenuti multimediali.

Ottieni un elemento multimediale

Per recuperare un elemento multimediale, chiama mediaItems.get utilizzando la proprietà mediaItemId. La richiesta restituisce un singolo elemento multimediale.

mediaItem contiene proprietà, come ID, descrizione e URL. La le informazioni aggiuntive all'interno di photo o video si basano sui metadati contenuti 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 della foto è simile a questa. La foto contiene metadati per gli elementi fotografici.

{
  "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 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 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 tramite i relativi identificatori, richiama mediaItems.batchGet utilizzando i mediaItemId.

La richiesta restituisce un elenco MediaItemResults nell'ordine degli identificatori degli elementi multimediali forniti nella richiesta. Ogni risultato contiene un oggetto MediaItem o Status se si è verificato un errore.

Il numero massimo di elementi multimediali che puoi richiedere in una chiamata è 50. L'elenco di gli elementi multimediali non devono contenere identificatori duplicati e non possono essere vuoti.

REST

Ecco una richiesta GET che mostra l'accesso riuscito e non riuscito elementi multimediali. Specifica ogni identificatore dell'elemento multimediale come nuovo Parametro di query mediaItemIds come parte 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 dei contenuti multimediali elementi. Usando i vari URL di base, l'app può scaricare gli elementi multimediali o mostrare gli elementi multimediali all'interno dell'app. Gli URL di base sono stringhe che vengono incluso nella risposta quando elenchi gli album o accedi a elementi multimediali. Sono sono validi per 60 minuti e richiedono parametri aggiuntivi in quanto non possono essere utilizzati dall'indirizzo IP interno.

I vari URL di base sono:

  • baseUrl: accedi direttamente alla foto e alla miniatura di un video o scarica i byte del video.
  • coverPhotoBaseUrl: accedi direttamente alla foto di copertina dell'album.
  • profilePictureBaseUrl: accedi direttamente alla foto del profilo del proprietario di una mediaItem.
di Gemini Advanced.

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 dell'immagine, ad esempio una foto o una miniatura per video, devi specificare le dimensioni che intendi visualizzare dell'applicazione (in modo che l'immagine possa essere ridimensionata dimensioni mantenendo le proporzioni). Per farlo, concatena l'URL di base con le dimensioni richieste come mostrato in gli esempi.

Esempi:

base-url=wmax-width-hmax-height

Ecco un esempio per visualizzare un elemento multimediale di larghezza non superiore a 2048 px, ma non superiore a 1024 px:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Descrizione

Il parametro c di ritaglio.

Se vuoi ritagliare l'immagine esattamente come larghezza e altezza. le dimensioni specificate, concatena l'URL di base con parametro facoltativo -c insieme al parametro obbligatorio Parametri w e h.

La dimensione (in pixel) deve essere compresa nell'intervallo [1, 16383]. Se larghezza o altezza dell'immagine, superano le dimensioni richieste, immagine ridimensionata e ritagliata (mantenendo le proporzioni).

Esempi:

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

In questo esempio, l'applicazione visualizza un elemento multimediale che esattamente 256 px di larghezza per 256 px di altezza, ad esempio miniatura:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

Descrizione

Il parametro download, d.

Se vuoi scaricare l'immagine conservando tutti i metadati EXIF ad eccezione dei metadati posizione, concatena l'URL di base con Parametro 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

Ecco l'elenco di opzioni che puoi utilizzare con gli URL dei video base:

Parametro
dv

Descrizione

Per accedere ai byte di un video mediaItem, concatena baseUrl con il video scaricato, dv .

Il parametro dv richiede un'alta qualità, transcodificata del video originale. Il parametro non è compatibile con w e h parametri.

Gli URL di base per il download dei video possono richiedere alcuni secondi e restituire byte. Per impostazione predefinita, i download dei video utilizzano la codifica H.264. Se la codifica H.264 non riesce, verrà utilizzato VP9.

Prima di utilizzare questo parametro, verifica che l'elemento multimediale Il campo mediaMetadata.status è READY. Altrimenti, se l'elemento multimediale non è finita, potresti ricevere .

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:

Consulta la tabella degli URL di base delle immagini per consultare alcuni esempi.

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 sia elementi foto 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 foto in movimento, utilizza Il parametro dv come faresti per scaricare dagli URL di base dei video.

w, h, c e d

Descrizione

Per recuperare l'elemento fotografico di un elemento multimediale foto in movimento, utilizza per gli URL di base delle immagini.