Google Photos Library API の以前のドキュメントを表示しています。

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

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

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

アプリケーションでユーザーの写真や動画を長期間キャッシュに保存しないでください。ただし、ユースケースによっては、必要に応じてメディアアイテム ID を保存またはキャッシュに保存できます。また、ユーザーデータにアクセスする場合はプライバシーに関する義務が適用される点に注意してください。

必要な認可スコープ

メディアアイテムにアクセスするには、以下の承認スコープのうち少なくとも 1 つをアプリでリクエストする必要があります。レスポンスで返されるメディアアイテムへのアクセス権は、リクエストしたスコープによって異なります。

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

RESTJavaPHP

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

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
}

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
}

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

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

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

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

RESTJavaPHP

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

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
}

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` パラメータと必須の `w` および `h` パラメータをベース URL に連結します。サイズ（ピクセル単位）は 1 ～ 16, 383 の範囲内である必要があります。画像の幅または高さがリクエストしたサイズを超える場合、画像は縮小され、切り取られます（縦横比は維持されます）。例: `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 パラメータと必須の 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 パラメータは、少なくとも 1 つの画像のベース URL パラメータとともに使用する必要があります。例: `base-url`=w`max-width`-h`max-height`-no 次の例では、幅 1,280 px、高さ 720 px で、再生ボタンのオーバーレイを含まない動画サムネイルを表示します。 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 px、高さ 720 px で、再生ボタンのオーバーレイを含まない動画サムネイルを表示します。

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

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

必要な認可スコープ

メディア項目

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

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

ベース URL

画像のベース URL

動画のベース URL

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

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

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

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

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