미디어 항목 액세스

애플리케이션은 반환된 미디어 항목을 저장하는 대신 사진 라이브러리 또는 앨범의 콘텐츠를 나열하도록 호출한 후 미디어 항목의 ID를 저장해야 합니다. 미디어 항목의 콘텐츠가 변경될 수 있고 일정 시간이 지나면 응답에 포함된 URL이 만료되기 때문입니다. 미디어 항목 ID는 사용자 라이브러리 내의 사진이나 동영상과 같은 미디어 항목을 고유하게 식별합니다.

애플리케이션은 사용자의 사진이나 동영상을 오랜 시간 동안 캐시하면 안 되지만 사용 사례에 따라 필요한 만큼 미디어 항목 ID를 저장 또는 캐시할 수도 있습니다. 또한 사용자 데이터 액세스에는 개인 정보 보호 의무가 적용됩니다.

필수 승인 범위

미디어 항목에 액세스하려면 앱이 다음 승인 범위 중 하나 이상을 요청해야 합니다. 응답에 반환된 미디어 항목에 대한 액세스 권한은 요청한 범위에 따라 다릅니다.

  • photoslibrary.readonly를 사용하면 사용자 라이브러리에 있는 모든 미디어 항목에 액세스할 수 있습니다.
  • photoslibrary.readonly.appcreateddata는 앱에서 만든 미디어 항목에만 액세스를 허용합니다.

미디어 항목

mediaItem는 Google 포토 라이브러리에 업로드된 사진이나 동영상과 같은 미디어를 나타냅니다. 이는 최상위 수준 객체이며 속성은 기본 미디어 유형에 따라 다를 수 있습니다.

다음 표에는 mediaItem 속성이 나와 있습니다.

속성
id 객체를 식별하는 데 사용되는 안정적인 영구 ID입니다.
description Google 포토에 표시되는 미디어 항목에 대한 설명입니다.
baseUrl 원시 바이트에 액세스하는 데 사용됩니다. 자세한 내용은 기본 URL을 참고하세요.
productUrl

Google 포토 내의 이미지 링크 이 링크는 개발자만 열 수 없고 사용자만 열 수 있습니다. URL은 라이브러리의 미디어 항목을 가리킵니다. 앨범 검색을 통해 URL을 가져온 경우 앨범 내의 항목을 가리킵니다.

mimeType 미디어 유형을 쉽게 식별하는 데 도움이 되는 미디어 항목 유형입니다(예: image/jpg).
filename 항목의 정보 섹션 내에 있는 Google 포토 앱에서 사용자에게 표시되는 미디어 항목의 파일 이름입니다.
mediaMetadata photo 또는 video와 같은 미디어의 기본 유형에 따라 다릅니다. 페이로드를 줄이기 위해 필드 마스크를 사용할 수 있습니다.
contributorInfo

이 필드는 미디어 항목이 이 앱에서 만든 공유 앨범에 있고 사용자가 photoslibrary.sharing 범위를 부여한 경우에만 채워집니다.

이 미디어 항목을 추가한 참여자에 관한 정보를 포함합니다. 자세한 내용은 미디어 공유를 참고하세요.

미디어 항목 가져오기

미디어 항목을 검색하려면 mediaItemId를 사용하여 mediaItems.get을 호출하세요. 요청에서 단일 미디어 항목을 반환합니다.

mediaItem에는 ID, 설명, URL 등의 속성이 포함됩니다. photo 또는 video 내 추가 정보는 파일 내의 메타데이터에 기반합니다. 일부 속성은 표시되지 않을 수 있습니다. ContributorInfo에는 공유 앨범에 속한 항목의 메타데이터가 포함됩니다. 이 필드는 사용자가 photoslibrary.sharing 승인 범위를 부여한 공유 앨범의 콘텐츠를 나열할 때만 포함됩니다.

미디어 항목이 동영상인 경우 동영상 파일이 먼저 처리되어야 합니다. mediaItem에는 mediaMetadata 내에 동영상 파일의 처리 상태를 설명하는 status 필드가 포함됩니다. 새로 업로드된 파일은 READY이 사용되기 전에 먼저 값이 PROCESSINGvideoProcessingStatus을 반환합니다. 동영상 미디어 항목의 baseUrl는 동영상이 처리될 때까지 사용할 수 없습니다.

REST

다음은 GET 요청입니다.

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

사진 미디어 항목의 응답은 다음과 같습니다. 사진 속성에는 사진 항목의 메타데이터가 포함됩니다.

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

동영상 미디어 항목의 응답은 다음과 같습니다. 동영상 속성에는 동영상 항목의 메타데이터가 포함됩니다.

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

Java

사진 속성에는 사진 항목의 메타데이터가 포함됩니다.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...
    if (metadata.hasPhoto()) {
      // This media item is a photo and has additional photo metadata
      Photo photoMetadata = metadata.getPhoto();
      String cameraMake = photoMetadata.getCameraMake();
      String cameraModel = photoMetadata.getCameraModel();
      float aperture = photoMetadata.getApertureFNumber();
      int isoEquivalent = photoMetadata.getIsoEquivalent();
      // ...
    }
  }
  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

동영상 속성에는 동영상 항목의 메타데이터가 포함됩니다.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...

    if (metadata.hasVideo()) {
      // This media item is a video and has additional video metadata
      Video videoMetadata = metadata.getVideo();
      VideoProcessingStatus status = videoMetadata.getStatus();
      if (status.equals(VideoProcessingStatus.READY)) {
        // This video media item has been processed
        String cameraMake = videoMetadata.getCameraMake();
        String cameraModel = videoMetadata.getCameraModel();
        double fps = videoMetadata.getFps();
        // ...
      }
    }
  }

  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

2,399필리핀

사진 속성에는 사진 항목의 메타데이터가 포함됩니다.

try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $photoMetadata = $metadata->getPhoto();
        if (!is_null($photoMetadata)) {
            // This media item is a photo and has additional photo metadata
            $cameraMake = $photoMetadata->getCameraMake();
            $cameraModel = $photoMetadata->getCameraModel();
            $aperture = $photoMetadata->getApertureFNumber();
            $isoEquivalent = $photoMetadata->getIsoEquivalent();
            // ...
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

동영상 속성에는 동영상 항목의 메타데이터가 포함됩니다.

  try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $videoMetadata = $metadata->getVideo();
        if (!is_null($videoMetadata)) {
            // This media item is a video and has additional video metadata
            if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
            // This video media item has been processed
                $cameraMake = $videoMetadata->getCameraMake();
                $cameraModel = $videoMetadata->getCameraModel();
                $fps = $videoMetadata->getFps();
                // ...
            }
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

여러 미디어 항목 가져오기

식별자로 여러 미디어 항목을 검색하려면 mediaItemId를 사용하여 mediaItems.batchGet를 호출하세요.

요청은 요청에 제공된 미디어 항목 식별자 순서대로 MediaItemResults 목록을 반환합니다. 각 결과에는 MediaItem 또는 오류가 있는 경우 Status가 포함됩니다.

호출 한 번에 요청할 수 있는 최대 미디어 항목 수는 50개입니다. 미디어 항목 목록은 중복 식별자를 포함해서는 안 되며 비워 둘 수 없습니다.

REST

다음은 미디어 항목의 액세스 성공과 실패를 보여주는 GET 요청입니다. 요청의 일부로 각 미디어 항목 식별자를 새 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

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

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

Java

try {
  // List of media item IDs to retrieve
  List<String> mediaItemIds = Arrays
      .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");

  // Get a list of media items using their IDs
  BatchGetMediaItemsResponse response = photosLibraryClient
      .batchGetMediaItems(mediaItemIds);

  // Loop over each result
  for (MediaItemResult result : response.getMediaItemResultsList()) {

    // Each MediaItemresult contains a status and a media item
    if (result.hasMediaItem()) {
      // The media item was successfully retrieved, get some properties
      MediaItem item = result.getMediaItem();
      String id = item.getId();
      // ...
    } else {
      // If the media item is not set, an error occurred and the item could not be loaded
      // Check the status and handle the error
      Status status = result.getStatus();
      // ...
    }

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

2,399필리핀

try {

    // List of media item IDs to retrieve
    $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];

    // Get a list of media items using their IDs
    $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);

    // Loop over each result
    foreach ($response->getMediaItemResults() as $itemResult) {

        // Each MediaItemresult contains a status and a media item
        $mediaItem = $itemResult->getMediaItem();

        if(!is_null($mediaItem)){
            // The media item was successfully retrieved, get some properties
            $id = $mediaItem->getId();
            // ...
        } else {
            // If the media item is null, an error occurred and the item could not be loaded
        }
    }

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

기본 URL

Google 포토 라이브러리 API 내의 기본 URL을 사용하면 미디어 항목의 바이트에 액세스할 수 있습니다. 앱은 다양한 기본 URL을 사용하여 미디어 항목을 다운로드하거나 앱 내의 미디어 항목을 표시할 수 있습니다. 기본 URL은 앨범을 나열하거나 미디어 항목에 액세스할 때 응답에 포함되는 문자열입니다. 60분 동안 유효하며 그대로 사용할 수 없으므로 추가 매개변수가 필요합니다.

다양한 기본 URL은 다음과 같습니다.

  • baseUrl: 사진, 동영상의 썸네일 또는 다운로드 동영상 바이트에 직접 액세스합니다.
  • coverPhotoBaseUrl: 앨범의 표지 사진에 직접 액세스합니다.
  • profilePictureBaseUrl: mediaItem 소유자의 프로필 사진에 직접 액세스합니다.

이미지 기본 URL

다음은 이미지 기본 URL과 함께 사용할 수 있는 옵션 목록입니다.

매개변수
w, h

설명

너비, w, 높이, h 매개변수

동영상의 사진 또는 썸네일과 같은 이미지 미디어 항목에 액세스하려면 애플리케이션에 표시할 크기를 지정해야 합니다. 그래야 가로세로 비율을 유지하면서 이미지를 이러한 크기로 조정할 수 있습니다. 이렇게 하려면 예와 같이 기본 URL을 필수 측정기준과 연결합니다.

예:

base-url=wmax-width-hmax-height

다음은 너비가 2048픽셀 이하, 높이가 1024픽셀 이하인 미디어 항목을 표시하는 예입니다.

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

설명

자르기, c 매개변수

지정한 너비 및 높이 크기로 이미지를 자르려면 필수 wh 매개변수와 함께 기본 URL을 선택사항인 -c 매개변수와 연결합니다.

크기 (픽셀 단위)는 [1, 16383] 범위 내에 있어야 합니다. 이미지의 너비 또는 높이가 요청된 크기를 초과하면 이미지가 축소되고 잘립니다 (가로세로 비율 유지).

예:

base-url=wmax-width-hmax-height-c

이 예에서 애플리케이션은 정확히 너비 256픽셀, 높이 256픽셀인 미디어 항목(예: 썸네일)을 표시합니다.

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

설명

다운로드, d 매개변수

위치 메타데이터를 제외한 모든 Exif 메타데이터가 포함된 이미지를 다운로드하려면 기본 URL을 d 매개변수와 연결합니다.

예:

base-url=d

이 예에서는 애플리케이션이 위치 메타데이터를 제외한 모든 메타데이터가 포함된 이미지를 다운로드합니다.

https://lh3.googleusercontent.com/p/Az....XabC=d

동영상 기본 URL

다음은 동영상 기본 URL과 함께 사용할 수 있는 옵션 목록입니다.

매개변수
dv

설명

동영상 mediaItem의 바이트에 액세스하려면 baseUrl를 다운로드 동영상 dv 매개변수와 연결합니다.

dv 매개변수는 원본 동영상의 트랜스코딩된 고품질 버전을 요청합니다. 이 매개변수는 wh 매개변수와 호환되지 않습니다.

동영상 다운로드의 기본 URL에서 바이트를 반환하는 데 최대 몇 초 정도 걸릴 수 있습니다.

이 매개변수를 사용하기 전에 미디어 항목의 mediaMetadata.status 필드가 READY인지 확인합니다. 그렇지 않으면 미디어 항목의 처리가 완료되지 않은 경우 오류가 발생할 수 있습니다.

예:

base-url=dv

다음 예에서는 동영상의 바이트를 다운로드하는 방법을 보여줍니다.

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c, d

설명

동영상 썸네일에 액세스하려면 이미지 기본 URL 매개변수를 사용하세요.

기본적으로 모든 동영상 썸네일에는 재생 버튼의 오버레이가 포함됩니다. 이 오버레이를 삭제하려면 -no 매개변수를 참조하세요.

예:

예시는 이미지 기본 URL 표를 참조하세요.

no

설명

썸네일 오버레이 삭제, no 매개변수

재생 버튼의 오버레이 없이 동영상의 썸네일을 가져오려면 기본 URL을 no 매개변수와 연결합니다.

no 매개변수는 이미지 기본 URL 매개변수 중 하나 이상과 함께 사용해야 합니다.

예:

base-url=wmax-width-hmax-height-no

다음 예는 너비가 정확히 1280x720픽셀이며 재생 버튼 오버레이를 포함하지 않는 동영상 썸네일을 표시합니다.

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

모션 사진 기본 URL

모션 사진에는 사진과 동영상 요소가 모두 포함됩니다. 모션 사진 baseUrl 요청에 이미지 기본 URL 또는 동영상 기본 URL의 매개변수를 사용할 수 있습니다.

매개변수
dv

설명

모션 사진 미디어 항목의 동영상 요소를 검색하려면 동영상 기본 URL에서 다운로드할 때와 마찬가지로 dv 매개변수를 사용합니다.

w, h, c, d

설명

모션 사진 미디어 항목의 사진 요소를 가져오려면 이미지 기본 URL 형식을 사용합니다.