Po wywołaniu listy zawartości biblioteki zdjęć lub albumu zamiast zapisywania zwróconych elementów multimedialnych aplikacja powinna przechowywać ich identyfikatory. Dzieje się tak, ponieważ zawartość elementów multimedialnych może się zmienić, a po pewnym czasie adresy URL podane w odpowiedzi wygasną. Identyfikator elementu multimedialnego jednoznacznie identyfikuje element multimedialny, np. zdjęcie lub film w bibliotece użytkownika.
Pamiętaj, że aplikacja nie powinna zapisywać zdjęć ani filmów użytkownika w pamięci podręcznej przez długi czas, ale w zależności od przypadku użycia identyfikator elementu multimedialnego możesz przechowywać lub buforować na tak jak to konieczne. Pamiętaj też, że dostęp do danych użytkowników podlega zobowiązaniom dotyczącym prywatności.
Wymagane zakresy autoryzacji
Aby aplikacja mogła uzyskać dostęp do elementów multimedialnych, musi zażądać co najmniej jednego 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 elementów multimedialnych w bibliotece użytkownikaphotoslibrary.readonly.appcreateddata
zezwala na dostęp tylko do elementów multimedialnych utworzonych przez aplikację,
Elementy multimedialne
mediaItem
reprezentuje multimedia, np. zdjęcie lub film, które zostały przesłane do biblioteki Zdjęć Google. Jest obiektem najwyższego poziomu i jego właściwości mogą się różnić w zależności od typu mediów.
W tabeli poniżej znajdziesz listę właściwości mediaItem
:
Właściwości | |
---|---|
id |
Trwały, stabilny identyfikator służący do identyfikacji obiektu. |
description |
Opis elementu multimedialnego w postaci widocznej w Zdjęciach Google. |
baseUrl |
Służy do uzyskiwania dostępu do nieprzetworzonych bajtów. Więcej informacji znajdziesz w sekcji Podstawowe adresy URL. |
productUrl |
Link do zdjęcia w Zdjęciach Google. Tylko użytkownik nie może otworzyć tego linku. Adresy URL wskazują element multimedialny w bibliotece. Jeśli adres URL został pobrany z wyszukiwania albumu, wskazuje element w albumie. |
mimeType |
Typ elementu multimedialnego, który ułatwia identyfikację typu multimediów (np. image/jpg ). |
filename |
Nazwa pliku z elementem multimedialnym widoczna dla użytkownika w aplikacji Zdjęcia Google (w sekcji informacji o elemencie). |
mediaMetadata |
Różni się w zależności od typu multimediów, np. photo lub video .
Aby zmniejszyć ładunek, możesz użyć masek pól.
|
contributorInfo |
To pole jest wypełniane tylko wtedy, gdy element multimedialny znajduje się w albumie udostępnionym utworzonym przez tę aplikację, a użytkownik przyznał zakres Zawiera informacje o współtwórcy, który dodał dany element multimedialny. Więcej informacji znajdziesz w artykule Udostępnianie multimediów. |
Pobierz element multimedialny
Aby pobrać element multimedialny, wywołaj element mediaItems.get, korzystając z komponentu mediaItemId
. Żądanie zwraca jeden element multimedialny.
Pole mediaItem
zawiera właściwości takie jak identyfikator, opis i adres URL. Dodatkowe informacje w photo
lub video
zależą od metadanych w pliku. Nie wszystkie właściwości mogą być widoczne. ContributorInfo
zawiera metadane dotyczące elementów, które są częścią albumu udostępnionego. To pole jest uwzględniane tylko podczas wyświetlania zawartości udostępnionego albumu, w przypadku którego użytkownik przyznał zakres autoryzacji photoslibrary.sharing
.
Jeśli element multimedialny to film, najpierw trzeba przetworzyć plik wideo. Pole mediaItem
zawiera w komponencie mediaMetadata
pole status
, które opisuje stan przetwarzania pliku wideo. Nowo przesłany plik zwraca najpierw parametr videoProcessingStatus
z wartością PROCESSING
, a dopiero potem READY
. Element baseUrl
elementu multimedialnego wideo jest niedostę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ź dotycząca elementu multimedialnego zdjęcia wygląda tak. Właściwość zdjęcia 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ź dotycząca elementu multimedialnego 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ść zdjęcia 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ść video 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ść video 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 metodę mediaItems.batchGet
, używając parametrów mediaItemId
.
Żądanie zwraca listę MediaItemResults
w kolejności identyfikatorów elementów multimedialnych podanych w żądaniu. Każdy wynik zawiera MediaItem
lub Status
, jeśli wystąpił błąd.
Maksymalna liczba elementów multimedialnych, o które możesz poprosić w ramach jednego połączenia, to 50. Lista elementów multimedialnych nie może zawierać zduplikowanych identyfikatorów i nie może być pusta.
REST
Oto żądanie GET pokazujące udany i nieudany dostęp do elementów multimedialnych. Określ każdy identyfikator elementu multimedialnego jako nowy parametr zapytania mediaItemIds
w żądaniu:
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 następującą 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 multimedialnych. Korzystając z różnych podstawowych adresów URL, aplikacja może pobierać elementy multimedialne lub wyświetlać je w samej aplikacji. Podstawowe adresy URL to ciągi tekstowe dołączane do odpowiedzi, gdy otwierasz listę albumów lub elementy multimedialne. Są ważne przez 60 minut i wymagają dodatkowych parametrów, ponieważ nie można ich używać w obecnej postaci.
Różne podstawowe adresy URL to:
baseUrl
: bezpośredni dostęp do zdjęcia, miniatury filmu lub pobrania bajtów filmu.coverPhotoBaseUrl
: bezpośredni dostęp do zdjęcia na okładkę albumu.profilePictureBaseUrl
: umożliwia bezpośredni dostęp do zdjęcia profilowego właściciela kontamediaItem
.
Podstawowe adresy URL obrazów
Oto lista opcji, których możesz używać z podstawowymi adresami URL obrazów:
Parametr | |
---|---|
w , h |
Opis Szerokość, Aby uzyskać dostęp do multimedialnego elementu graficznego, takiego jak zdjęcie lub miniatura filmu, musisz określić wymiary, które chcesz wyświetlać w aplikacji (tak aby obraz mógł być 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, w którym można wyświetlić element multimedialny o wymiarach nie większej niż 2048 pikseli i maksymalnie 1024 pikseli: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Opis Parametr Jeśli chcesz przyciąć obraz do określonej szerokości i wysokości, połącz podstawowy adres URL z opcjonalnym parametrem Rozmiar (w pikselach) powinien mieścić się w zakresie [1, 16383]. Jeśli szerokość lub wysokość obrazu przekracza żądany rozmiar, obraz jest pomniejszany i przycinany (z zachowaniem proporcji). Przykłady: base-url=wmax-width-hmax-height-c W tym przykładzie aplikacja wyświetla element multimedialny o szerokości dokładnie 256 pikseli i wysokości 256 pikseli, na przykład miniatury: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Opis Parametr pobierania, Jeśli chcesz pobrać obraz zawierający wszystkie metadane Exif z wyjątkiem metadanych lokalizacji, połącz podstawowy adres URL z parametrem 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ć z podstawowymi adresami URL filmów:
Parametr | |
---|---|
dv |
Opis Aby uzyskać dostęp do bajtów filmu Parametr dv żąda wysokiej jakości transkodowanej wersji oryginalnego filmu. Parametr jest niezgodny z parametrami w i h. Zwrócenie bajtów przez podstawowe adresy URL pobierania filmów może potrwać kilka sekund. Zanim użyjesz tego parametru, sprawdź, czy pole Przykłady: base-url=dv Z przykładu poniżej dowiesz się, jak pobrać bajty 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 podstawowego adresu URL obrazu. Domyślnie wszystkie miniatury filmów zawierają nakładkę z przyciskiem odtwarzania. Aby usunąć nakładkę, sprawdź parametr -no. Przykłady: Przykłady znajdziesz w tabeli bazowych adresów URL obrazów. |
no |
Opis Usuń nakładkę z miniaturą, parametr Jeśli chcesz pobrać miniaturę filmu bez nakładki z przyciskiem odtwarzania, połącz podstawowy adres URL z parametrem no. Parametr no musi być używany z co najmniej jednym z podstawowych parametrów adresu URL obrazu. Przykłady: base-url=wmax-width-hmax-height-no Poniższy przykład pokazuje miniaturę filmu, która ma dokładnie 1280 pikseli szerokości i 720 pikseli wysokości i nie zawiera nakładki z przyciskiem odtwarzania: https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
Podstawowe adresy URL zdjęć ruchomych
Zdjęcia ruchome zawierają zarówno elementy graficzne, jak i wideo. W przypadku żądań baseUrl
zdjęć ruchomych możesz używać parametrów z podstawowych adresów URL obrazów lub podstawowych adresów URL filmów.
Parametr | |
---|---|
dv |
Opis Aby pobrać element wideo z elementu multimedialnego ze zdjęciem ruchomym, użyj parametru |
w , h , c i d |
Opis Aby pobrać element zdjęcia z elementu multimedialnego ze zdjęciem ruchomym, użyj formatu podstawowych adresów URL obrazu. |