アプリによって作成されたメディア アイテムにアクセスする

フォト ライブラリまたはアルバムのコンテンツをリストする呼び出しを実行した後、アプリケーションでは、返されたメディア アイテムを保存するのではなく、メディア アイテムの ID を保存する必要があります。これは、メディア アイテムのコンテンツは変更される可能性があり、一定の時間が経過するとレスポンスに含まれる URL が期限切れになるためです。メディア アイテム ID によって、ユーザーのライブラリ内にある写真や動画などのメディア アイテムを一意に識別できます。

必要な認可スコープ

アプリによって作成されたメディア アイテムにアクセスするには、photoslibrary.readonly.appcreateddata スコープが必要です。スコープの詳細については、認可スコープをご覧ください。

メディア項目

mediaItem は、Google フォト ライブラリにアップロードされた写真や動画などのメディアを表します。これは最上位のオブジェクトであり、基盤となるメディアタイプによってプロパティが異なる場合があります。

次の表に、mediaItem のプロパティを示します。

プロパティ
id オブジェクトを識別するために使用される、永続的に変わらない ID。
description Google フォト内に表示されるメディア アイテムの説明。
baseUrl 未加工のバイト列にアクセスするために使用されます。詳細については、ベース URL をご覧ください。
productUrl

Google フォト内の画像へのリンク。デベロッパーがこのリンクを開くことはできず、ユーザーのみが開くことができます。URL はライブラリ内のメディア アイテムを参照します。URL がアルバム検索から取得された場合は、アルバム内のアイテムを参照します。
mimeType メディアのタイプを簡単に識別するためのメディア アイテムのタイプ（例: image/jpg）。
filename Google フォト アプリでユーザーに表示されるメディア アイテムのファイル名（アイテムの情報セクション内に表示）。
mediaMetadata メディアの基盤となるタイプ（photo や video など）によって異なります。ペイロードを減らすためにフィールド マスクを使用できます。

メディア アイテムを取得する

メディア アイテムを取得するには、mediaItemId を使用して mediaItems.get を呼び出します。リクエストは単一のメディア アイテムを返します。

mediaItem には、ID、説明、URL などのプロパティが含まれます。photo または video に含まれる追加情報は、ファイル内のメタデータに基づきます。プロパティがすべて存在するとは限りません。

メディア アイテムが動画の場合、はじめに動画ファイルを処理する必要があります。mediaItem には、動画ファイルの処理状態を記録する status フィールドが mediaMetadata 内に含まれています。新しくアップロードされたファイルはまず値 PROCESSING の videoProcessingStatus を返し、その後 READY になって使用できるようになります。動画のメディア アイテムの 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"
  }
}

複数のメディア アイテムを取得する

ID を指定して複数のメディア アイテムを取得するには、mediaItemId を使用して mediaItems.batchGet を呼び出します。

このリクエストは、リクエストで指定されたメディア アイテム ID の順序で MediaItemResults のリストを返します。各結果には MediaItem が含まれます。エラーが発生した場合は Status が含まれます。

1 回の呼び出しでリクエストできるメディア アイテムは最大で 50 個です。メディア アイテムのリストに重複した ID を含めることはできません。また、リストを空にすることもできません。

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

ベース URL

Google Photos API のベース URL を使用すると、メディア アイテムの未加工バイトにアクセスできるため、アプリでメディア アイテムをダウンロードまたは表示できます。これらの URL は、アルバムのリストを取得する（Library API）場合や、メディア アイテムにアクセスする（Library API と Picker API の両方）場合のレスポンスに含まれます。ベース URL を正しく機能させるには、追加のパラメータが必要です。

Picker API の場合:

すべての PickedMediaItem.mediaFile オブジェクトには baseUrl が含まれます。

ベース URL は 60 分間有効ですが、ユーザーが Google アカウントの設定でアプリの権限を取り消した場合は、それより早く期限切れになることがあります。

Library API の場合:

ベース URL は 60 分間アクティブのままです。

ベース URL には次のものがあります。

  • baseUrl: 写真、動画のサムネイルに直接アクセスしたり、動画のバイト列をダウンロードしたりできます。
  • coverPhotoBaseUrl: アルバムのカバー写真に直接アクセスできます。
  • profilePictureBaseUrl: mediaItem のオーナーのプロフィール写真に直接アクセスできます。

画像のベース URL

以下に示すのは、画像のベース URL で使用できるオプションのリストです。

パラメータ
w、h

説明

幅 w パラメータと高さ h パラメータ。

画像のメディア アイテム（写真、動画のサムネイルなど）にアクセスするには、アプリケーションで表示する予定のサイズを指定する必要があります（これにより、アスペクト比を維持しながら画像をこのサイズに拡大または縮小できます）。これを行うには、例に示すように、必要なサイズをベース URL に連結します。

例:

base-url=wmax-width-hmax-height

以下の例は、幅が最大 2,048 ピクセル、高さが最大 1,024 ピクセルのメディア アイテムを示しています。

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

説明

切り抜き、c パラメータ。

指定した幅と高さで正確なサイズに画像を切り抜くには、オプションの -c パラメータと必須の w パラメータおよび h パラメータをベース URL に連結します。

サイズ（ピクセル単位）は 1 ～ 16, 383 の範囲内である必要があります。画像の幅または高さがリクエストしたサイズを超える場合、画像は縮小され、切り取られます（縦横比は維持されます）。

例:

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 パラメータは、元の動画の高品質なトランスコード バージョンをリクエストします。このパラメータは、w パラメータと h パラメータとは互換性がありません。

動画ダウンロードのベース 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 パラメータの少なくとも 1 つとともに使用する必要があります。

例:

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 からダウンロードする場合と同様に、dv パラメータを使用します。
w、h、c、d

説明

モーション フォト メディア アイテムの写真要素を取得するには、画像のベース URL の形式を使用します。