Dostęp do elementów multimedialnych

Po wywołaniu metody list() do wyświetlenia zawartości biblioteki zdjęć lub albumu aplikacja powinna przechowywać identyfikatory zwróconych multimediów zamiast samych multimediów. Dzieje się tak, ponieważ zawartość elementów multimedialnych może się zmieniać, a po pewnym czasie adresy URL zawarte w odpowiedzi tracą ważność. Identyfikator elementu multimedialnego jednoznacznie identyfikuje element multimedialny, np. zdjęcie lub film, w bibliotece użytkownika.

Pamiętaj, że aplikacja nie powinna przechowywać zdjęcia lub filmu użytkownika w pamięci podręcznej przez długi czas, ale w zależności od przypadku użycia możesz przechowywać lub zapisywać w pamięci podręcznejidentyfikator elementu multimedialnego tak długo w razie potrzeby. Pamiętaj też, że dostęp do danych użytkownika podlega obowiązkom związanym z prywatnością.

Wymagane zakresy autoryzacji

Aby uzyskać dostęp do elementów multimedialnych, aplikacja musi poprosić o co najmniej 1 z tych zakresów autoryzacji. Dostęp do elementów multimedialnych zwróconych w odpowiedzi zależy od żądanych zakresów.

  • photoslibrary.readonly umożliwia dostęp do wszystkich multimediów w bibliotece użytkownika.
  • photoslibrary.readonly.appcreateddata zezwala na dostęp tylko do multimediów utworzonych przez aplikację.

Elementy multimedialne

mediaItem to reprezentacja multimediów, takich jak zdjęcie lub film, które zostały przesłane do biblioteki Zdjęć Google. Jest to obiekt najwyższego poziomu, którego właściwości mogą się różnić w zależności od typu nośnika.

Właściwości mediaItem:

Właściwości
id Stały, stabilny identyfikator służący do identyfikacji obiektu.
description Opis elementu multimedialnego w Zdjęciach Google.
baseUrl Służy do uzyskiwania dostępu do nieprzetworzonych bajtów. Więcej informacji znajdziesz w sekcji Adresy URL podstawowe.
productUrl

link do obrazu w Zdjęciach Google. Tego linku nie może otworzyć deweloper, tylko użytkownik. Adresy URL wskazują element multimedialny w bibliotece. Jeśli adres URL został pobrany z wyszukiwania albumu, wskazuje element w albumie.

mimeType Typ elementu multimedialnego ułatwiający identyfikację typu mediów (np. image/jpg).
filename Nazwa pliku elementu multimedialnego widocznego dla użytkownika w aplikacji Zdjęcia Google (w sekcji informacji o elemencie).
mediaMetadata Różne w zależności od typu nośnika, np. photo lub video. Aby zmniejszyć ładunek, można użyć masek pól.
contributorInfo

To pole jest wypełniane tylko wtedy, gdy element multimedialny znajduje się w wspólnym albumie utworzonym przez tę aplikację, a użytkownik przyznał dostęp w zakresie photoslibrary.sharing.

Zawiera informacje o autorze, który dodał ten element multimedialny. Więcej informacji znajdziesz w artykule Udostępnianie multimediów.

Pobieranie elementu multimedialnego

Aby pobrać element multimedialny, wywołaj funkcję mediaItems.get, korzystając z parametru mediaItemId. Żądanie zwraca pojedynczy element multimedialny.

mediaItem zawiera właściwości takie jak identyfikator, opis i adres URL. Dodatkowe informacje w tabeli photo lub video są oparte na metadanych zawartych w pliku. Niektóre właściwości mogą być niedostępne. ContributorInfo zawiera metadane elementów należących do albumu udostępnionego. To pole jest uwzględniane tylko wtedy, gdy wyświetlane są treści udostępnionego albumu, w którym użytkownik przyznał uprawnienia photoslibrary.sharing zakresu autoryzacji.

Jeśli element multimedialny to film, najpierw musi zostać przetworzony plik wideo. mediaItem zawiera pole status w mediaMetadata, które opisuje stan przetwarzania pliku wideo. Nowo przesłany plik zwraca najpierw videoProcessingStatus o wartości PROCESSING, a dopiero potem READY w użyciu. baseUrlelementu multimedialnego wideo nie jest dostępny, dopóki film nie zostanie przetworzony.

REST

Oto żądanie GET:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

Odpowiedź dla elementu multimedialnego z zdjęciem wygląda tak. Właściwość photo zawiera metadane elementów zdjęć.

{
  "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"
  }
}

Odpowiedź na element multimediów wideo wygląda tak. Właściwość video zawiera metadane elementów wideo.

{
  "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

Właściwość photo zawiera metadane elementów zdjęć.

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
}

Właściwość wideo zawiera metadane elementów wideo.

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

Właściwość zdjęcia zawiera metadane elementów zdjęć.

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
}

Właściwość wideo zawiera metadane elementów wideo.

  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
}

Pobierz wiele elementów multimedialnych

Aby pobrać wiele elementów multimedialnych według ich identyfikatorów, wywołaj funkcję mediaItems.batchGet, używając parametrów mediaItemId.

Żądanie zwraca listę MediaItemResults w kolejności identyfikatorów mediów podanych w żądaniu. Każdy wynik zawiera wartość MediaItem lub Status, jeśli wystąpił błąd.

Maksymalna liczba elementów multimediów, o które możesz poprosić w jednym wywołaniu, to 50. Lista elementów multimedialnych nie może zawierać zduplikowanych identyfikatorów ani nie może być pusta.

REST

Oto żądanie GET, które pokazuje udane i nieudane próby dostępu do multimediów. Określ każdy identyfikator elementu multimedialnego jako nowy parametr zapytania mediaItemIds w ramach żądania:

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

Żądanie GET zwraca tę odpowiedź:

{
  "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
}

Podstawowe URL-e

Podstawowe adresy URL w interfejsie Google Photos Library API umożliwiają dostęp do bajtów elementów multimediów. Korzystając z różnych adresów URL podstawowych, aplikacja może pobierać lub wyświetlać elementy multimedialne. Adresy URL podstawowe to ciągi znaków, które są uwzględniane w odpowiedzi, gdy wyświetlasz listę albumów lub uzyskujesz dostęp do elementów multimedialnych. Są ważne przez 60 minut i wymagają dodatkowych parametrów, ponieważ nie można ich używać w takiej postaci.

Różne podstawowe adresy URL to:

  • baseUrl: bezpośredni dostęp do zdjęcia lub miniatury filmu oraz pobieranie bajtów filmu.
  • coverPhotoBaseUrl: bezpośredni dostęp do zdjęcia okładki albumu.
  • profilePictureBaseUrl: bezpośredni dostęp do zdjęcia profilowego właściciela mediaItem.

Podstawowe adresy URL obrazów

Oto lista opcji, których możesz używać w przypadku adresów URL bazowych obrazów:

Parametr
w, h

Opis

Szerokość w i wysokość h.

Aby uzyskać dostęp do elementu multimediów z obrazem, np. zdjęcia lub miniatury filmu, musisz określić wymiary, które mają być wyświetlane w aplikacji (aby obraz mógł zostać przeskalowany do tych wymiarów przy zachowaniu współczynnika proporcji). Aby to zrobić, połącz podstawowy adres URL z wymaganymi wymiarami, jak pokazano w przykładach.

Przykłady:

base-url=wmax-width-hmax-height

Oto przykład wyświetlania elementu multimedialnego, który ma maksymalnie 2048 pikseli i nie może być wyższy niż 1024 piksele:

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

Opis

Parametr crop, c.

Jeśli chcesz przyciąć obraz do określonych szerokości i wysokości określonych przez Ciebie wymiarów, połącz podstawowy adres URL z opcjonalnym parametrem -c oraz wymaganymi parametrami w i h.

Rozmiar (w pikselach) powinien mieścić się w zakresie [1, 16383]. Jeśli szerokość lub wysokość obrazu przekracza wymagany rozmiar, obraz jest zmniejszany i przycinany (przy zachowaniu współczynnika proporcji).

Przykłady:

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

W tym przykładzie aplikacja wyświetla element multimedialny o dokładnej szerokości 256 pikseli i wysokości 256 pikseli, na przykład miniaturę:

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

Opis

Parametr download, d.

Jeśli chcesz pobrać obraz z zachowaniem wszystkich metadanych Exif oprócz metadanych lokalizacji, połącz podstawowy adres URL za pomocą parametru d.

Przykłady:

base-url=d

W tym przykładzie aplikacja pobiera obraz ze wszystkimi metadanymi oprócz metadanych lokalizacji:

https://lh3.googleusercontent.com/p/Az....XabC=d

Podstawowe adresy URL filmów

Oto lista opcji, których możesz używać w przypadku adresów URL filmów:

Parametr
dv

Opis

Aby uzyskać dostęp do bajtów filmu mediaItem, połącz parametr baseUrl z parametrem dv pobierania filmu.

Parametr dv żąda wysokiej jakości transkodowanej wersji oryginalnego filmu. Parametr jest niezgodny z parametrami w i h.

Zwrócenie bazowych adresów URL pobieranych filmów może potrwać kilka sekund.

Przed użyciem tego parametru sprawdź, czy pole mediaMetadata.status elementów multimediów ma wartość READY. Jeśli jednak przetwarzanie Twojego elementu multimedialnego nie zostało ukończone, może pojawić się błąd.

Przykłady:

base-url=dv

Ten przykład pokazuje, jak pobrać liczbę bajtów filmu:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c i d

Opis

Aby uzyskać dostęp do miniatury filmu, użyj dowolnego z parametrów adresu URL podstawowego obrazu.

Domyślnie wszystkie miniatury filmów zawierają nakładkę z przyciskiem odtwarzania. Aby usunąć nakładkę, użyj parametru -no.

Przykłady:

Przykłady znajdziesz w tabeli adresów URL obrazów podstawowych.
no

Opis

Usunięcie nakładki miniatury, parametr no.

Jeśli chcesz pobrać miniaturę filmu bez nakładki przycisku odtwarzania, połącz podstawowy adres URL z parametrem no.

Parametru no należy używać z co najmniej 1 z parametrów podstawowego adresu URL obrazu.

Przykłady:

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

W tym przykładzie miniatura filmu ma dokładnie 1280 pikseli szerokości i 720 pikseli wysokości oraz nie zawiera nałożonego przycisku odtwarzania:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

Adresy URL zdjęć ruchomych

Zdjęcia ruchome zawierają zarówno elementy zdjęć, jak i filmów. W przypadku żądań dotyczących zdjęć w ruchu baseUrl możesz używać parametrów z adresów URL bazowych obrazu lub adresów URL bazowych filmu.

Parametr
dv

Opis

Aby pobrać element wideo z multimediów z użyciem zdjęcia w ruchu, użyj parametru dv w taki sam sposób jak w przypadku adresów URL filmów podstawowych.
w, h, c i d

Opis

Aby pobrać element zdjęcia z elementu multimedialnego z ruchomym zdjęciem, użyj formatu adresów URL bazowych zdjęć.