Dostęp do elementów multimedialnych tworzonych w aplikacji

Po wywołaniu metody list(), która zwraca zawartość biblioteki lub albumu zdjęć, 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ę zmieniać, a po pewnym czasie adresy URL uwzględnione w odpowiedzi tracą ważność. 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, takich jak zdjęcie lub film, które zostały przesłane do biblioteki Zdjęć Google. Jest to obiekt najwyższego poziomu, a jego 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 surowych 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, który ułatwia identyfikację typu mediów (np. image/jpg).
filename Nazwa pliku elementu multimedialnego wyświetlanego użytkownikowi w aplikacji Zdjęcia Google (w sekcji z informacjami o elemencie).
mediaMetadata Różne w zależności od typu mediów, np. photolub video. Aby zmniejszyć ładunek, można użyć masek pól.

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 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 element videoProcessingStatusoraz wartość PROCESSING, zanim zostanie READY do użycia. 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ź na element multimediów ze 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 dotyczące 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 udane i nieudane próby dostępu do multimediów. W ramach żądania określ każdy identyfikator elementu multimedialnego 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 i wyświetlanie. Te adresy URL są uwzględniane w odpowiedziach podczas wyświetlania albumów (interfejs Library API) lub uzyskiwania dostępu do multimediów (interfejsy Library API i Picker API). 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, miniatury filmu lub pobranie filmu w formacie binarnym.
  • 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

Parametry szerokość, w i wysokość, h.

Aby uzyskać dostęp do elementu multimedialnego 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, c.

Jeśli chcesz przyciąć obraz do określonych przez siebie wymiarów, złącz podstawowy adres URL z opcjonalnym parametrem -c oraz obowiązkowymi 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, np. miniaturę:

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

Opis

Parametr download, d.

Jeśli chcesz pobrać obraz, zachowując wszystkie metadane Exif (z wyjątkiem metadanych lokalizacji), połącz podstawowy adres URL z parametrem 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 powoduje przesłanie wysokiej jakości wersji transkodowanej oryginalnego filmu. Parametr jest niezgodny z parametrami w i h.

Pobieranie adresów URL filmów może potrwać do kilku sekund.

Przed użyciem tego parametru sprawdź, czy pole mediaMetadata.status elementów multimediów ma wartość READY. Jeśli jednak Twój element multimedialny nie został w pełni przetworzony, może pojawić się błąd.

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 parametrów adresu URL podstawowego obrazu.

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

Przykłady:

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

Opis

Parametr no umożliwiający usunięcie nakładki z miniaturą.

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

Na przykładzie poniżej widać miniaturę filmu o szerokości 1280 pikseli i wysokości 720 pikseli bez 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. Do żądań dotyczących zdjęć w ruchu baseUrl możesz używać parametrów z adresów URL podstawowych obrazu lub adresów URL podstawowych 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 bazowych filmów.
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ęć.