メディア アイテムの一覧表示と取得

ユーザーが Picker API を使用してメディア アイテムを選択すると、そのアイテムに関する情報を取得してコンテンツにアクセスできます。このガイドでは、メディア アイテムのリストと取得のプロセスについて説明します。

始める前に

  • フローを確認する: 写真選択プロセス全体の概要については、Picker API の使用を開始するをご覧ください。
  • メディア アイテムの選択を完了: ユーザーがセッションからメディア アイテムを正しく選択していることを確認します。詳しくは、セッションに関するガイドをご覧ください。
  • 必要な認可スコープを確認する: セッションの操作には photospicker.mediaitems.readonly スコープが必要です。スコープの詳細については、認可スコープをご覧ください。

選択したメディア アイテムを一覧表示する

  1. mediaItems.list エンドポイントを使用する: クエリ パラメータとして sessionId を指定して、https://photospicker.googleapis.com/v1/mediaItems への GET リクエストを行います。

  2. ページ分けを処理する（必要に応じて）:

    ユーザーが大量のアイテムを選択した場合、レスポンスはページングされる場合があります。結果の後続のページを取得するには、レスポンスの nextPageToken を使用します。

  3. メディア アイテムを処理します。レスポンスには、選択したメディア アイテムを表す PickedMediaItem オブジェクトの配列が含まれます。これらのオブジェクトには、次のような重要な詳細情報が含まれます。

    • id: メディア アイテムの一意の識別子。
    • baseUrl: さまざまな解像度でメディア アイテムのコンテンツにアクセスするための URL を作成できるベース URL。
    • mimeType: メディア アイテムの MIME タイプ（image/jpeg、video/mp4 など）。

選択したメディア アイテムを取得する

リクエストを承認するための https://www.googleapis.com/auth/photospicker.mediaitems.readonly スコープを持つ有効な OAuth 2.0 アクセス トークンがあることを確認します。

  • コンテンツ URL を作成します。PickedMediaItem オブジェクトの baseUrl を使用します。解像度またはファイル形式を baseUrl に追加します。詳しくは、ベース URL に関するセクションをご覧ください。

  • コンテンツを取得する: メディア アイテムのベース URL に GET リクエストを送信します。レスポンスには、メディア アイテム（画像または動画）のバイト数が含まれます。使用できる baseURL オプションはいくつかあります。

ベース 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 の形式を使用します。