フォト ライブラリまたはアルバムの内容を一覧表示する呼び出しを行った後、アプリケーションでは、返されたメディア アイテムを保存する代わりに、そのメディア アイテムの ID を保存する必要があります。これは、メディア アイテムの内容が変更され、一定の時間が経過するとレスポンスに含まれる URL が期限切れになるためです。メディア アイテム ID は、ユーザーのライブラリ内にある写真や動画などのメディア アイテムを一意に識別します。
アプリではユーザーの写真や動画を長期間キャッシュに保存しないでください。ただし、ユースケースによっては、必要に応じてメディア アイテム ID を保存またはキャッシュに保存できます。また、ユーザーデータへのアクセスにはプライバシーに関する義務が適用されます。
必要な認可スコープ
メディア アイテムにアクセスするには、次の承認スコープのうち少なくとも 1 つをアプリでリクエストする必要があります。レスポンスで返されるメディア アイテムへのアクセス権は、リクエストしたスコープによって異なります。
photoslibrary.readonly
は、ユーザーのライブラリ内のすべてのメディア アイテムへのアクセスを許可します。photoslibrary.readonly.appcreateddata
を使用すると、アプリによって作成されたメディア アイテムにのみアクセスできます。
メディア項目
mediaItem
は、Google フォト ライブラリにアップロードされた写真や動画などのメディアを表します。これは最上位のオブジェクトであり、そのプロパティは基になるメディアタイプによって異なる場合があります。
次の表に、mediaItem
のプロパティを示します。
プロパティ | |
---|---|
id |
オブジェクトの識別に使用される永続的で不変の ID。 |
description |
Google フォト内に表示されるメディア アイテムの説明。 |
baseUrl |
RAW バイトにアクセスするために使用されます。詳細については、ベース URL をご覧ください。 |
productUrl |
Google フォト内の画像へのリンク。このリンクは、デベロッパーが開くことはできず、ユーザーだけが開くことができます。ライブラリ内のメディア アイテムを指す URL を指定します。アルバム検索で取得した URL は、アルバム内のアイテムを指します。 |
mimeType |
メディアのタイプを簡単に識別するためのメディア アイテムのタイプ(例: image/jpg )。 |
filename |
Google フォト アプリでユーザーに表示されるメディア アイテムのファイル名(アイテムの情報セクション内)。 |
mediaMetadata |
メディアの基になるタイプ(photo 、video など)によって異なります。
ペイロードを削減するには、フィールド マスクを使用できます。 |
contributorInfo |
このフィールドが入力されるのは、このアプリで作成された共有アルバムにメディア アイテムが含まれ、ユーザーが このメディア アイテムを追加した投稿者に関する情報が含まれます。詳しくは、メディアを共有するをご覧ください。 |
メディア アイテムを取得する
メディア アイテムを取得するには、mediaItemId
を使用して mediaItems.get を呼び出します。リクエストは単一のメディア アイテムを返します。
mediaItem
には、ID、説明、URL などのプロパティが含まれます。photo
または video
内の追加情報は、ファイル内のメタデータに基づきます。すべてのプロパティが存在するとは限りません。ContributorInfo
には、共有アルバムの一部であるアイテムのメタデータが含まれます。このフィールドは、ユーザーが photoslibrary.sharing
承認スコープを付与した共有アルバムのコンテンツをリストする場合にのみ含められます。
メディア アイテムが動画の場合は、最初に動画ファイルを処理する必要があります。mediaItem
の mediaMetadata
内に status
フィールドがあり、動画ファイルの処理状態を記述します。新しくアップロードされたファイルは、READY
になる前に値 PROCESSING
を含む videoProcessingStatus
を返します。動画メディア アイテムの baseUrl
は、動画の処理が完了するまで使用できません。
REST
GET リクエストは次のようになります。
GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id Content-type: application/json Authorization: Bearer oauth2-token
写真のメディア アイテムに対するレスポンスは次のようになります。Photo プロパティには、写真アイテムのメタデータが含まれます。
{ "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" } }
動画メディア アイテムに対するレスポンスは次のようになります。video プロパティには、動画アイテムのメタデータが含まれます。
{ "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
Photo プロパティには、写真アイテムのメタデータが含まれます。
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 }
video プロパティには、動画アイテムのメタデータが含まれます。
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 }
PHP
Photo プロパティには、写真アイテムのメタデータが含まれます。
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 }
video プロパティには、動画アイテムのメタデータが含まれます。
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
を呼び出します。
このリクエストは、リクエストで指定されたメディア アイテム ID 順に MediaItemResults
のリストを返します。各結果には MediaItem
が含まれます。エラーが発生した場合は Status
が含まれます。
1 回の呼び出しでリクエストできるメディア アイテムの最大数は 50 です。メディア アイテムのリストには、重複する識別子を含めることはできません。また、リストを空にすることもできません。
REST
次に示すのは、メディア アイテムへのアクセスの成功と失敗を示す GET リクエストです。リクエストの一部として、各メディア アイテムの ID を新しい 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 }
PHP
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 Photos Library API 内のベース URL を使用すると、メディア アイテムのバイトにアクセスできます。アプリはさまざまなベース URL を使用して、メディア アイテムをダウンロードしたり、アプリ内でメディア アイテムを表示したりできます。ベース URL は、アルバムを一覧表示したりメディア アイテムにアクセスしたりするときにレスポンスに含まれる文字列です。これらは 60 分間有効で、そのまま使用することはできないため、追加のパラメータが必要です。
さまざまなベース URL は次のとおりです。
baseUrl
: 写真や動画のサムネイルに直接アクセスしたり、動画のバイトをダウンロードしたりできます。coverPhotoBaseUrl
: アルバムのカバー写真に直接アクセスできます。profilePictureBaseUrl
:mediaItem
のオーナーのプロフィール写真に直接アクセスします。
画像のベース URL
イメージのベース URL で使用できるオプションは次のとおりです。
パラメータ | |
---|---|
w 、h |
説明 幅( 画像メディア アイテム(写真や動画のサムネイルなど)にアクセスするには、アプリに表示するサイズを指定する必要があります(これにより、アスペクト比を維持したまま、画像をこれらのサイズに拡大できます)。これを行うには、例に示すように、ベース URL に必要なディメンションを連結します。 例: base-url=wmax-width-hmax-height 次の例では、幅 2,048 ピクセル以下、高さ 1,024 ピクセル以下のメディア アイテムを表示します。 https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
説明 切り抜き、 指定した幅と高さに正確に画像を切り抜くには、オプションの サイズ(ピクセル単位)は [1, 16383] の範囲内で指定してください。画像の幅と高さのいずれかがリクエストされたサイズを超えると、画像は縮小され、トリミングされます(アスペクト比は維持されます)。 例: base-url=wmax-width-hmax-height-c この例では、アプリケーションは幅 256 ピクセル、高さ 256 ピクセルのメディア アイテム(サムネイルなど)を表示します。 https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
説明 ダウンロード( 位置情報のメタデータを除くすべての Exif メタデータを保持する画像をダウンロードするには、ベース URL を 例: base-url=d この例では、アプリは位置情報メタデータを除くすべてのメタデータを含む画像をダウンロードします。 https://lh3.googleusercontent.com/p/Az....XabC=d |
動画のベース URL
動画のベース URL で使用できるオプションは次のとおりです。
パラメータ | |
---|---|
dv |
説明 動画 dv パラメータは、元の動画の高品質コード変換バージョンをリクエストします。このパラメータは、w パラメータおよび h パラメータと互換性がありません。 動画ダウンロードのベース URL がバイトを返すまでに数秒かかることがあります。 このパラメータを使用する前に、メディア アイテムの 例: base-url=dv 次の例は、動画のバイトをダウンロードする方法を示しています。 https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w 、h 、c 、d |
説明 動画のサムネイルにアクセスするには、画像のベース URL パラメータのいずれかを使用します。 デフォルトでは、すべての動画のサムネイルに再生ボタンのオーバーレイが含まれます。このオーバーレイを削除するには、-no パラメータをご覧ください。 例: 例については、画像のベース URL の表をご覧ください。 |
no |
説明 サムネイル オーバーレイの削除、 再生ボタンのオーバーレイなしで動画のサムネイルを取得するには、ベース URL に no パラメータを連結します。 no パラメータは、少なくとも 1 つの画像のベース URL パラメータとともに使用する必要があります。 例: base-url=wmax-width-hmax-height-no 次の例では、幅 1,280 ピクセル、高さ 720 ピクセルで、再生ボタンのオーバーレイを含まない動画サムネイルを表示しています。 https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no |
モーション フォトベースの URL
モーション フォトには、写真要素と動画要素の両方が含まれます。モーション フォトの baseUrl
リクエストには、画像のベース URL または動画のベース URL のパラメータを使用できます。
パラメータ | |
---|---|
dv |
説明 モーション フォト メディア アイテムの動画要素を取得するには、動画のベース URL からダウンロードする場合と同様に、 |
w 、h 、c 、d |
説明 モーション フォト メディア アイテムのフォト要素を取得するには、画像のベース URL の形式を使用します。 |