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 を呼び出します。このリクエストでは 1 つのメディアアイテムが返されます。

mediaItem には、ID、説明、URL などのプロパティが含まれます。「 photo または video 内の追加情報は、その中のメタデータに基づきます。表示されます。プロパティがすべて存在するとは限りません。ContributorInfo にはメタデータが含まれています。共有アルバム内のアイテムを検索します。このフィールドは、ユーザーが photoslibrary.sharing 認可スコープを付与した共有アルバムのコンテンツをリストする場合にのみ含まれます。

メディアアイテムが動画の場合は、まず動画ファイルを処理する必要があります。「 mediaItem には、mediaMetadata 内の status フィールドが含まれています。動画ファイルの処理状態を確認できます。新しくアップロードされたファイルには videoProcessingStatus 最初に値 PROCESSING を割り当て、その前に READY を使用します。baseUrl 動画メディアアイテムは、動画の処理が完了するまで使用できません。

REST

以下は GET リクエストです。

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

写真のメディアアイテムに対するレスポンスは次のようになります。写真プロパティには、写真アイテムのメタデータが含まれます。

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

動画のメディアアイテムに対するレスポンスは次のようになります。動画プロパティには動画アイテムのメタデータが含まれます。

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

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

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

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` パラメータ。画像を適切な幅と高さに切り抜く場合ベース URL を省略可能な `-c` パラメータと必須のパラメータ `w` パラメータと `h` パラメータ。サイズ（ピクセル単位）は 1～16,383 の範囲内である必要があります。次のいずれかに該当する場合画像の幅または高さがリクエストされたサイズを超えた場合、画像が縮小および切り抜かれます（アスペクト比は維持されます）。例: `base-url`=w`max-width`-h`max-height`-c この例では、アプリケーションで表示されるメディアアイテムに（例: 幅 256 px、高さ 256 px にする）。サムネイル: 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 パラメータ。

画像を適切な幅と高さに切り抜く場合ベース URL を省略可能な -c パラメータと必須のパラメータ w パラメータと h パラメータ。

サイズ（ピクセル単位）は 1～16,383 の範囲内である必要があります。次のいずれかに該当する場合画像の幅または高さがリクエストされたサイズを超えた場合、画像が縮小および切り抜かれます（アスペクト比は維持されます）。

例:

base-url=wmax-width-hmax-height-c

この例では、アプリケーションで表示されるメディアアイテムに（例: 幅 256 px、高さ 256 px にする）。サムネイル:

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`=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 パラメータは、画像のベース URL のパラメータの少なくとも 1 つとともに使用する必要があります。

例:

base-url=wmax-width-hmax-height-no

次の例では、幅 1,280 ピクセル、高さ 720 ピクセルの動画サムネイルを表示し、再生ボタンのオーバーレイは含めていません。

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

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

モーションフォトには、写真と動画の両方の要素が含まれています。次のパラメータを使用できます: 画像のベース URL モーションフォトの baseUrl リクエストの動画ベース 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