Wyświetlanie utworzonych w aplikacji elementów multimedialnych i albumów

Wymagane zakresy autoryzacji

Wyświetlanie treści utworzonych w aplikacji wymaga uprawnienia photoslibrary.readonly.appcreateddata. Więcej informacji o zakresach znajdziesz w artykule Zakresy autoryzacji.

Omówienie

Interfejs Library API umożliwia wyświetlanie listy elementów multimedialnych utworzonych w aplikacji i dostęp do nich.

Oto niektóre z kluczowych funkcji listowania elementów multimedialnych:

• wyświetlanie elementów multimedialnych z konkretnych albumów utworzonych w aplikacji lub całej biblioteki utworzonej w aplikacji;

• Zastosuj filtry (data, kategoria treści, typ multimediów), aby zawęzić wyniki.

• Pobieraj obiekty mediaItem z podstawowymi informacjami, takimi jak bezpośrednie linki i metadane.

Wyświetlenie zawartości biblioteki i albumu zwraca listę elementów multimedialnych. Wzbogacenia, które są częścią albumu, nie są uwzględniane. Elementy multimedialne opisują zdjęcie, film lub inne multimedia. mediaItem zawiera bezpośredni link do elementu, link do elementu w Zdjęciach Google oraz inne odpowiednie metadane. Więcej informacji znajdziesz w artykułach na temat uzyskiwania dostępu do elementów multimedialnych i mediaItems.

Lista albumów utworzonych przez aplikację

Możesz wyświetlić albumy utworzone przez Twoją aplikację za pomocą albums.list.

GET https://photoslibrary.googleapis.com/v1/albums

{
  "albums": [
    {
      "id": "album-id",
      "title": "album-title",
      "productUrl": "album-product-url",
      "coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
      "coverPhotoMediaItemId": "album-cover-media-item-id",
      "isWriteable": "whether-you-can-write-to-this-album",
      "mediaItemsCount": "number-of-media-items-in-album"
    },
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Każdy zwrócony album ma identyfikator, za pomocą którego można pobrać jego zawartość, jak pokazano w sekcji Lista zawartości albumu. Zawiera też tytuł i liczbę elementów multimedialnych.

productUrl wskazuje album w Zdjęciach Google, który użytkownik może otworzyć.

Plik coverPhotoMediaItemId zawiera identyfikator zasobu multimedialnego, który reprezentuje zdjęcie na okładce tego albumu. Aby uzyskać dostęp do tego zdjęcia na okładkę, kliknij coverPhotoBaseUrl. Nie należy używać tagu coverPhotoBaseUrl bezpośrednio bez podania dodatkowych parametrów.

Odpowiedź zawiera też element nextPageToken. Więcej informacji znajdziesz w artykule Przejście na inną stronę.

Odpowiedź dotycząca pustych albumów różni się tym, że mediaItemsCount i coverPhotoMediaItemId mają domyślnie wartość 0 i są pomijane w odpowiedzi REST. Pamiętaj też, że coverPhotoBaseUrl wskazuje domyślny obrazek zastępczy.

Wyświetlanie listy zawartości biblioteki utworzonej przez aplikację

Możesz wyświetlić listę wszystkich multimediów z biblioteki Zdjęć Google użytkownika, które zostały utworzone przez Twoją aplikację. Nie dotyczy to elementów zarchiwizowanych ani usuniętych. Możesz wyświetlić elementy multimedialne według ich zawartości, daty i innych właściwości, stosując filtry.

Aby wyświetlić listę elementów multimedialnych, wybierz mediaItems.list.

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Odpowiedź zawiera listę elementów multimedialnych uporządkowanych od najnowszego do najstarszego. Więcej informacji znajdziesz w sekcji mediaItems. Zawiera on też nextPageToken, który jest opisany bardziej szczegółowo w sekcji Przejścia.

Wyświetl listę zawartości albumu

Aby wyświetlić wszystkie elementy multimedialne w albumie, dodaj pole albumId do żądania wyszukiwania. Więcej informacji o albumId znajdziesz w artykule Wyświetlanie albumów. Jeśli wartość albumId jest nieprawidłowa, zwracany jest błąd Bad Request. Jeśli identyfikator jest prawidłowy, ale album nie istnieje dla uwierzytelnionego użytkownika, zostanie zwrócony błąd Not Found. Więcej informacji o obsługiwaniu błędów znajdziesz w artykułach Wskazówki dotyczące wydajności i Sprawdzone metody.

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

{
  "mediaItems": [
    ...
  ],
  "nextPageToken": "token-for-pagination"
}

Odpowiedź zawiera nextPageToken i listę elementów multimedialnych. W przeciwieństwie do listy zawartości biblioteki elementy multimedialne są zwracane według kolejności w albumie. Więcej informacji znajdziesz w sekcjach mediaItems i Podział na strony. Użytkownik może edytować zamówienie w interfejsie Zdjęć Google.

Jeśli ustawisz opcję albumId, nie będzie można zastosować filtra podczas wyświetlania zawartości albumu. Spowoduje to błąd Bad Request.

Podział na strony w przypadku REST

Aby zwiększyć wydajność, metody zwracające dużą liczbę wyników (np. metody listy) mogą dzielić odpowiedź na strony. Maksymalna liczba wyników na każdej stronie jest określana przez parametr pageSize.

W przypadku wywołań funkcji mediaItems.search i mediaItems.list domyślny rozmiar strony to 25 elementów. Zalecamy ten rozmiar strony, ponieważ zapewnia on równowagę między rozmiarem odpowiedzi a poziomem współczynnika wypełnienia. Maksymalny rozmiar strony w przypadku żądań wyszukiwania elementów multimedialnych i list to 100 elementów.

Domyślny i zalecany rozmiar strony z listą albumów to 20 albumów, a maksymalnie 50 albumów.

Jeśli liczba dostępnych wyników jest większa niż rozmiar strony, odpowiedź zawiera nextPageToken, co wskazuje aplikacji, że na serwerze są jeszcze inne wyniki.

Przykład

Musisz dodać nextPageToken do kolejnych żądań w parametrze pageToken, jak pokazano w tym przykładzie. Określ parametr pageToken wraz z innymi parametrami wymaganymi do wykonania operacji w treści żądania lub jako parametr zapytania.

Prośba nr 1

{
  "pageSize": "5",
  "filters": { … }
}

Odpowiedź 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Prośba nr 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Odpowiedź 2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Powtarzaj ten wzór, dopóki nie znikną wszystkie obiekty nextPageToken.

Pole nextPageToken jest prawidłowe tylko w przypadku tego samego żądania. Jeśli jakieś parametry ulegną zmianie, wcześniej użytego parametru nextPageToken nie należy używać w tym samym żądaniu.