앱에서 만든 미디어 항목 및 앨범 나열

필수 승인 범위

앱에서 만든 콘텐츠를 등록하려면 photoslibrary.readonly.appcreateddata 범위가 필요합니다. 범위에 관한 자세한 내용은 승인 범위를 참고하세요.

개요

Library API를 사용하면 애플리케이션에서 만든 미디어 항목을 나열하고 액세스할 수 있습니다.

미디어 항목 나열의 몇 가지 주요 기능은 다음과 같습니다.

  • 앱에서 만든 특정 앨범 또는 전체 앱에서 만든 라이브러리의 미디어 항목 나열

  • 등록정보를 작성할 때 필터(날짜, 콘텐츠 카테고리, 미디어 유형)를 적용하여 검색 결과 범위를 좁힙니다.

  • 직접 링크 및 메타데이터와 같은 필수 세부정보가 포함된 mediaItem 객체를 검색합니다.

라이브러리와 앨범 콘텐츠를 나열하면 미디어 항목 목록이 반환됩니다. 앨범에 포함된 보강은 포함되지 않습니다. 미디어 항목은 사진, 동영상 또는 기타 미디어를 나타냅니다. 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"
}

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

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

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

응답에는 nextPageToken도 포함됩니다. 자세한 내용은 페이지로 나누기를 참고하세요.

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

앱에서 만든 라이브러리 콘텐츠 표시

앱에서 만든 사용자의 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"
}

응답에는 최근 항목부터 오래된 항목 순으로 정렬된 미디어 항목 목록이 포함됩니다. 자세한 내용은 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"
}

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

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

REST의 페이징

성능을 개선하기 위해 많은 수의 결과를 반환하는 메서드(예: 목록 메서드)는 응답을 페이지로 나눌 수 있습니다. 각 페이지의 최대 결과 수는 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를 동일한 요청에 사용해서는 안 됩니다.