このページは Cloud Translation API によって翻訳されました。

メディアアイテムにアクセスする

フォトライブラリまたはアルバムの内容を一覧表示する呼び出しを行った後、アプリケーションでは、返されたメディアアイテムを保存する代わりに、そのメディアアイテムの 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`	このフィールドが入力されるのは、このアプリで作成された共有アルバムにメディアアイテムが含まれ、ユーザーが `photoslibrary.sharing` スコープを付与している場合のみです。このメディアアイテムを追加した投稿者に関する情報が含まれます。詳しくは、メディアを共有するをご覧ください。

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

メディアアイテムを取得するには、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`	説明幅（`w`）と高さ（`h`）のパラメータ。画像メディアアイテム（写真や動画のサムネイルなど）にアクセスするには、アプリに表示するサイズを指定する必要があります（これにより、アスペクト比を維持したまま、画像をこれらのサイズに拡大できます）。これを行うには、例に示すように、ベース URL に必要なディメンションを連結します。例: `base-url`=w`max-width`-h`max-height` 次の例では、幅 2,048 ピクセル以下、高さ 1,024 ピクセル以下のメディアアイテムを表示します。 https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
`c`	説明切り抜き、`c` パラメータ。指定した幅と高さに正確に画像を切り抜くには、オプションの `-c` パラメータとともにベース URL を連結し、必須の `w` パラメータと `h` パラメータを指定します。サイズ（ピクセル単位）は [1, 16383] の範囲内で指定してください。画像の幅と高さのいずれかがリクエストされたサイズを超えると、画像は縮小され、トリミングされます（アスペクト比は維持されます）。例: `base-url`=w`max-width`-h`max-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

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 パラメータとともにベース URL を連結し、必須の w パラメータと h パラメータを指定します。

サイズ（ピクセル単位）は [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 パラメータは、元の動画の高品質コード変換バージョンをリクエストします。このパラメータは、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 パラメータは、少なくとも 1 つの画像のベース URL パラメータとともに使用する必要があります。例: `base-url`=w`max-width`-h`max-height`-no 次の例では、幅 1,280 ピクセル、高さ 720 ピクセルで、再生ボタンのオーバーレイを含まない動画サムネイルを表示しています。 https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

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 パラメータは、少なくとも 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 からダウンロードする場合と同様に、`dv` パラメータを使用します。
`w`、`h`、`c`、`d`	説明モーションフォトメディアアイテムのフォト要素を取得するには、画像のベース URL の形式を使用します。

dv

説明

モーションフォトメディアアイテムの動画要素を取得するには、動画のベース URL からダウンロードする場合と同様に、dv パラメータを使用します。

w、h、c、d

説明

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

メディア アイテムにアクセスする

必要な認可スコープ

メディア項目

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

REST

Java

PHP

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

REST

Java

PHP

ベース URL

画像のベース URL

動画のベース URL

モーション フォトベースの URL

メディアアイテムにアクセスする

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

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

モーションフォトベースの URL