Po wywołaniu metody list(), która zwraca zawartość biblioteki zdjęć lub albumu, zamiast przechowywać zwrócone elementy multimediów, aplikacja powinna przechowywać identyfikatory tych elementów. Dzieje się tak, ponieważ zawartość elementów multimedialnych może się zmienić i po upływie określonego czasu adresy URL zawarte w odpowiedzi wygasną. Identyfikator elementu multimedialnego jednoznacznie identyfikuje element multimedialny, np. zdjęcie lub film w bibliotece użytkownika.
Wymagane zakresy autoryzacji
Dostęp do elementów multimedialnych utworzonych przez aplikację wymaga zakresu photoslibrary.readonly.appcreateddata. Więcej informacji o zakresach znajdziesz w artykule Zakresy autoryzacji.
Elementy multimedialne
mediaItem to reprezentacja multimediów, np. zdjęć lub filmów przesłanych 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 tabeli poniżej wymienione są właściwości mediaItem:
| Właściwości | |
|---|---|
id |
Stały, stabilny identyfikator służący do identyfikacji obiektu. |
description |
Opis elementu multimedialnego widoczny 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 wyświetlana użytkownikowi w aplikacji Zdjęcia Google (w sekcji z informacjami o elemencie). |
mediaMetadata |
Różne w zależności od typu nośnika, np. photo
lub video.
Aby zmniejszyć ładunek, możesz użyć masek pól.
|
Pobieranie elementu multimedialnego
Aby pobrać element multimedialny, wywołaj funkcję mediaItems.get, używając 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.
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ź dotycząca elementu multimedialnego ze zdjęciami 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 multimedialny 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"
}
}
Pobieranie wielu 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 być pusta.
REST
Oto żądanie GET, które pokazuje udany i nieudany dostęp do elementów multimedialnych. W ramach żądania podaj identyfikator każdego elementu multimediów jako nowy parametr zapytania mediaItemIds:
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."
}
}
]
}
Podstawowe URL-e
Adresy URL podstawowe w interfejsach API Zdjęć Google zapewniają dostęp do surowych bajtów elementów multimedialnych, co umożliwia aplikacji ich pobieranie lub wyświetlanie. Te adresy URL są uwzględniane w odpowiedziach, gdy wyświetla się lista albumów (interfejs Library API) lub uzyskuje dostęp do elementów multimedialnych (zarówno w interfejsach Library API, jak i selektorze). Pamiętaj, że prawidłowe działanie adresów URL podstawowych wymaga dodatkowych parametrów.
W przypadku interfejsu Picker API:
Wszystkie obiekty PickedMediaItem.mediaFile zawierają element baseUrl.
Adresy URL podstawowe pozostają aktywne przez 60 minut, ale mogą wygasnąć wcześniej, jeśli użytkownik cofnie uprawnienia aplikacji w ustawieniach konta Google.
W przypadku Library API:
Adresy URL podstawowe pozostają aktywne przez 60 minut.
Różne podstawowe adresy URL:
baseUrl: bezpośredni dostęp do zdjęcia lub miniatury filmu oraz do pobierania 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ścicielamediaItem.
Podstawowe adresy URL obrazu
Oto lista opcji, których możesz używać w przypadku bazowych adresów URL obrazów:
| Parametr | |
|---|---|
w, h |
Opis Szerokość 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 wymiary, których potrzebujesz, jak pokazano w przykładach. Przykłady: base-url=wmax-width-hmax-height Oto przykład wyświetlania elementu multimedialnego o szerokości nieprzekraczającej 2048 pikseli i wysokości nieprzekraczającej 1024 pikseli: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Opis Parametr crop, Jeśli chcesz przyciąć obraz do określonych przez siebie wymiarów, złą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 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 szerokości dokładnie 256 pikseli i wysokości 256 pikseli, np. miniaturę: https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
Opis Parametr download, Jeśli chcesz pobrać obraz, zachowując wszystkie metadane Exif (z wyjątkiem metadanych lokalizacji), złą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ć w przypadku adresów 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. Pobieranie adresów URL do pobrania filmów może potrwać do kilku sekund. Przed użyciem tego parametru sprawdź, czy pole Przykłady: base-url=dv Ten przykład pokazuje, 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 podstawowych parametrów adresu URL obrazu. Domyślnie wszystkie miniatury filmów zawierają nakładkę z przyciskiem odtwarzania. Aby usunąć tę nakładkę, sprawdź parametr -no. Przykłady: Przykłady znajdziesz w tabeli adresów URL obrazów podstawowych. |
no |
Opis Parametr Jeśli chcesz pobrać miniaturę filmu bez nakładki przycisku odtwarzania, połącz podstawowy adres URL z parametrem no. Parametr no musi być używany z co najmniej jednym z parametrów adresu URL bazowego 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 żądaniach 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 w elemencie multimedialnym ze zdjęciem ruchomym, użyj parametru |
w, h, c i d |
Opis Aby pobrać element zdjęcia w elemencie multimedialnym ze zdjęciem ruchomym, użyj formatu podstawowych adresów URL obrazu. |