이 페이지는 Cloud Translation API를 통해 번역되었습니다.

라이브러리 콘텐츠, 앨범, 미디어 항목 나열

필수 승인 범위

Google 포토 라이브러리 API에는 미디어 항목 및 앨범에 액세스하는 데 사용되는 여러 범위가 포함되어 있습니다. 다양한 호출에서 반환되는 미디어 항목은 개발자가 요청한 범위에 따라 다릅니다.

photoslibrary.readonly 범위를 사용하면 사용자 라이브러리에 있는 모든 미디어 항목에 액세스할 수 있습니다. photoslibrary.readonly.appcreateddata 범위는 앱에서 만든 미디어 항목에만 액세스를 허용합니다. 자세한 내용은 승인 범위를 참고하세요.

개요

API의 중요한 용도는 사용자가 Google 포토에 백업한 미디어 항목을 나열하는 것입니다. 특정 앨범 또는 사용자의 전체 라이브러리 (Google 포토 앱의 기본 뷰)에 있는 항목을 나열할 수 있습니다.

사용자 라이브러리의 항목을 나열할 때 지정된 날짜, 콘텐츠 카테고리 또는 미디어 유형과 일치하는 필터를 사용하여 사진을 선택할 수 있습니다. 이 기능은 앨범의 항목을 나열할 때는 지원되지 않습니다.

라이브러리 및 앨범 콘텐츠를 나열하면 미디어 항목 목록이 반환됩니다. 앨범에 포함된 보강 항목은 포함되지 않습니다. 미디어 항목은 사진, 동영상 또는 기타 미디어를 설명합니다. mediaItem에는 항목으로 연결되는 직접 링크, Google 포토의 항목으로 연결되는 링크, 기타 관련 메타데이터가 포함됩니다. 자세한 내용은 미디어 항목 액세스 및 mediaItems를 참고하세요.

앨범 나열

albums.list를 사용하여 사용자 앨범 목록을 검색할 수 있습니다.

REST

샘플 요청은 다음과 같습니다.

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

Java

try {
  // Make a request to list all albums in the user's library
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums();

  for (Album album : response.iterateAll()) {
    // Get some properties of an album
    String id = album.getId();
    String title = album.getTitle();
    String productUrl = album.getProductUrl();
    String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl();
    // The cover photo media item id field may be empty
    String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId();
    boolean isWritable = album.getIsWriteable();
    long mediaItemsCount = album.getMediaItemsCount();
  }

} catch (ApiException e) {
  // Handle error
}

2,399필리핀

try {
    // Make a request to list all albums in the user's library
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // Get some properties of an album
        $albumId = $album->getId();
        $title = $album->getTitle();
        $productUrl = $album->getProductUrl();
        $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl();
        // The cover photo media item id field may be empty
        $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId();
        $isWriteable = $album->getIsWriteable();
        $totalMediaItems = $album->getTotalMediaItems();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

반환된 각 앨범에는 앨범 콘텐츠 목록에 표시된 것처럼 앨범의 콘텐츠를 검색하는 데 사용할 수 있는 ID가 있습니다. 제목과 제목에 포함된 미디어 항목 수도 포함됩니다.

productUrl는 사용자가 열 수 있는 Google 포토 앨범을 가리킵니다.

coverPhotoMediaItemId에는 이 앨범의 표지 사진을 나타내는 미디어 항목 ID가 포함됩니다. 이 표지 이미지에 액세스하려면 coverPhotoBaseUrl를 사용하세요. 추가 매개변수를 지정하지 않고 coverPhotoBaseUrl를 직접 사용하면 안 됩니다.

사용자의 계정에서 생성되었거나 사용자 계정에 추가되었으며 앱이 공유한 앨범에는 추가 shareInfo 속성이 포함됩니다. 자세한 내용은 미디어 공유를 참고하세요.

앨범에 미디어 항목을 만들 수 있는지 나타내는 isWriteable 플래그도 있을 수 있습니다. 이 플래그가 반환되지 않으면 기본값은 false입니다. 다음을 포함하여 애플리케이션에 부여되는 액세스 권한에 따라 달라집니다.

앨범을 만든 사용자
공유 여부
사용자가 승인한 범위

기준 중 하나라도 변경되면 이 플래그가 변경될 수 있습니다. 자세한 내용은 앨범 만들기를 참고하세요. 응답에는 nextPageToken도 포함됩니다. 자세한 내용은 페이지로 나누기를 참고하세요.

빈 앨범에 대한 응답은 다음과 같은 점에서 다릅니다. mediaItemsCount 및 coverPhotoMediaItemId는 기본적으로 0으로 설정되고 REST 응답에서 생략됩니다. 또한 coverPhotoBaseUrl는 기본 자리표시자 이미지를 가리킵니다.

라이브러리 콘텐츠 나열

사용자의 Google 포토 라이브러리에 있는 모든 미디어 항목을 나열할 수 있습니다. 보관처리되거나 삭제된 항목은 제외됩니다. 필터를 적용하여 콘텐츠, 날짜 및 기타 속성을 기반으로 미디어 항목을 나열할 수 있습니다. 사용자가 Google 포토의 공유 탭에서 사용할 수 있는 항목을 라이브러리에 추가하지 않았다면 해당 항목은 이 목록에 포함되지 않습니다.

미디어 항목을 검색하려면 mediaItems.list를 호출합니다.

REST

샘플 요청은 다음과 같습니다.

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

GET 요청은 다음과 같은 응답을 반환합니다.

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

Java

try {
  // Make a request to list all media items in the user's library
  // Iterate over all the retrieved media items
  // Pagination is handled automatically
  ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems();
  for (MediaItem item : response.iterateAll()) {
    // Get some properties of a media item
    String id = item.getId();
    String description = item.getDescription();
    String mimeType = item.getMimeType();
    String productUrl = item.getProductUrl();
    String filename = item.getFilename();
  }
} catch (ApiException e) {
  // Handle error
}

2,399필리핀

try {
    // Make a request to list all media items in the user's library
    // Iterate over all the retrieved media items
    // Pagination is handled automatically
    $response = $photosLibraryClient->listMediaItems();
    foreach ($response->iterateAllElements() as $item) {
        // Get some properties of a media item
        /* @var $item \Google\Photos\Library\V1\MediaItem */
        $id = $item->getId();
        $description = $item->getDescription();
        $mimeType = $item->getMimeType();
        $productUrl = $item->getProductUrl();
        $filename = $item->getFilename();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

응답에는 미디어 항목 목록이 최신순으로 포함됩니다. 자세한 내용은 mediaItems를 참고하세요. 또한 nextPageToken도 포함되어 있습니다. 자세한 내용은 페이지로 나누기를 참고하세요.

앨범 콘텐츠 나열

앨범의 모든 미디어 항목을 나열하려면 검색 요청에 albumId 필드를 추가합니다. albumId에 관한 자세한 내용은 앨범 나열 및 공유 앨범 나열을 참고하세요. albumId가 유효하지 않으면 Bad Request 오류가 반환됩니다. ID는 유효하지만 인증된 사용자의 앨범이 없으면 Not Found 오류가 반환됩니다. 오류 처리에 관한 자세한 내용은 성능 팁과 권장사항을 참고하세요.

REST

샘플 요청은 다음과 같습니다.

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

POST 요청이 다음과 같은 응답을 반환합니다.

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

Java

try {
  // Make a request to list all media items in an album
  // Provide the ID of the album as a parameter in the searchMediaItems call
  // Iterate over all the retrieved media items
  SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId);

  for (MediaItem item : response.iterateAll()) {
    // ...
  }

} catch (ApiException e) {
  // Handle error
}

2,399필리핀

try {
    // Make a request to list all media items in an album
    // Provide the ID of the album as a parameter in the searchMediaItems call
    // Iterate over all the retrieved media items
    $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]);
    foreach ($response->iterateAllElements() as $item) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

응답에는 nextPageToken와 미디어 항목 목록이 포함됩니다. 라이브러리 콘텐츠를 나열할 때와 달리 미디어 항목은 앨범 순서에 따라 반환됩니다. 자세한 내용은 mediaItems 및 페이지로 나누기를 참고하세요. 사용자는 Google 포토 인터페이스에서 주문을 수정할 수 있습니다.

albumId를 설정하면 앨범 콘텐츠를 나열할 때 필터를 적용할 수 없습니다. 그렇게 하면 Bad Request 오류가 발생합니다.

공유 앨범 나열

사용자가 공유했거나 사용자와 공유된 모든 앨범의 목록을 검색할 수 있습니다. 이는 Google 포토 앱의 공유 탭과 유사합니다.

사용자가 Google 포토 라이브러리에 추가한 공유 앨범은 앨범 목록 호출에서도 반환됩니다. 라이브러리 API를 통해 공유 앨범을 나열하려면 다음 호출을 실행합니다.

REST

샘플 요청은 다음과 같습니다.

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

요청이 다음과 같은 결과를 반환합니다.

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

Java

try {
  // Make a request to list all albums that have been shared by the user
  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums();

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

2,399필리핀

try {
    // Make a request to list all albums that have been shared by the user
    // Iterate over all the albums in this list
    // Pagination is handled automatically
    $response = $photosLibraryClient->listSharedAlbums();
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

앨범 목록은 sharedAlbums에 포함되어 있습니다. 자세한 내용은 앨범 나열을 참고하세요. 응답에는 nextPageToken도 포함됩니다. 자세한 내용은 페이지로 나누기를 참고하세요.

앱에서 만들고 공유한 앨범에는 추가 shareInfo 속성이 포함됩니다. 자세한 내용은 미디어 공유를 참고하세요.

앱에서 만든 앨범 나열

다음 호출에서 excludeNonAppCreatedData를 true로 설정하여 앱에서 만든 앨범을 나열할 수 있습니다.

REST

다음은 사용자의 Google 포토 라이브러리에서 내 앱에 의해서만 만들어진 모든 앨범을 나열하기 위한 GET 요청입니다.

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

다음은 사용자의 Google 포토 라이브러리에서 내 앱에서만 만든 모든 공유 앨범을 나열하기 위한 GET 요청입니다.

GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Java

try {
  // Make a request to list all albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

try {
  // Make a request to list all shared albums that have been created by your app
  boolean excludeNonAppCreatedData = true;

  // Iterate over all the albums in this list
  // Pagination is handled automatically
  ListSharedAlbumsPagedResponse response =
      photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData);

  for (Album album : response.iterateAll()) {
    // ..
  }

} catch (ApiException e) {
  // Handle error
}

2,399필리핀

try {
    // Make a request to list all albums that have been created by your app
    $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

try {
    // Make a request to list all shared albums that have been created by your app
    $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]);

    // Iterate over all the albums in this list
    // Pagination is handled automatically
    foreach ($response->iterateAllElements() as $album) {
        // ...
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

REST의 페이지로 나누기

성능을 개선하기 위해 많은 수의 결과를 반환하는 메서드 (예: list 메서드)는 응답을 페이지로 나눌 수 있습니다. 각 페이지의 최대 결과 수는 pageSize 매개변수로 지정됩니다.

mediaItems:search 및 mediaItems:list 호출의 경우 기본 페이지 크기는 25개 항목입니다. 이 페이지 크기는 응답 크기와 유효노출률 간의 균형을 맞추기 때문에 권장됩니다. 미디어 항목 검색 및 목록 요청의 최대 페이지 크기는 항목 100개입니다.

앨범을 나열할 때 권장되는 기본 페이지 크기는 20개(앨범 최대 50개)입니다.

사용 가능한 결과 수가 페이지 크기보다 크면 응답에 nextPageToken가 포함됩니다. 이 응답은 서버에서 가져올 결과가 더 있음을 애플리케이션에 알립니다.

예

다음 예와 같이 pageToken 매개변수의 후속 요청에 nextPageToken를 추가해야 합니다. 요청 본문에 또는 쿼리 매개변수로 작업에 필요한 다른 매개변수와 함께 pageToken를 지정합니다.

요청 #1

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

응답 #1

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

요청 #2

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

응답 #2

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

더 이상 nextPageToken 객체가 없을 때까지 이 패턴을 계속합니다.

nextPageToken는 동일한 요청에서만 유효합니다. 매개변수가 변경되면 이전에 사용된 nextPageToken을 동일한 요청에서 사용해서는 안 됩니다.