必要な認可スコープ
photoslibrary.readonly
スコープを使用すると、
表示されます。
アプリによって作成されたコンテンツの検索とフィルタの適用には、
photoslibrary.readonly.appcreateddata
スコープ。スコープについて詳しくは
認可スコープをご覧ください。
使用可能なフィルタ
アプリで作成されたメディア アイテムのユーザーのライブラリで、特定の種類のメディアを検索できます。たとえば、動物のアイテムだけを 領収書の写真を除外できます。除外または アルバムやライブラリのリスティングにフィルタを適用して、特定のアイテムを含める。そこで、 次の 5 つのフィルタを使用できます。
- コンテンツ カテゴリ(
includedContentCategories
、excludedContentCategories
) - 期間(
dates
、ranges
) - 機能(
featureFilter
) - メディアタイプ(
mediaTypeFilter
) - アーカイブ済み状態(
includeArchivedMedia
)
albumId
が次の場合、mediaItems.search
リクエストでフィルタを使用しないでください。
あります。albumId が設定されているときにフィルタを使用すると、INVALID_ARGUMENT
のエラー(400)が返されます。
結果は、メディア アイテムの作成日時順に並べられます。並べ替え順 変更できます。
新しくアップロードしたメディアが検索結果に表示されるまで、しばらくお待ちください。メディア フィルタが適用されていない検索ですぐに表示されます。
将来の日付が設定されているメディア アイテムは、フィルタされた検索結果には表示されません。 フィルタされていない検索やアルバムの検索に表示されます。
フィルタを適用する
フィルタを適用するには、
mediaItems.search
、
filter
プロパティを指定します。
REST
POST リクエストは次のようになります。
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"filters": {
...
}
}
POST リクエストは次のレスポンスを返します。
{ "mediaItems": [ ... ], "nextPageToken": "token-for-pagination" }
Java
try { // Create a new Filter object Filters filters = Filters.newBuilder() // .setContentFilter(...) // .setDateFilter(...) // ... .build(); // Specify the Filter object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters); for (MediaItem item : response.iterateAll()) { // ... } } catch (ApiException e) { // Handle error }
PHP
try { $filtersBuilder = new FiltersBuilder(); // $filtersBuilder->addIncludedCategory(...); // $filtersBuilder->addDate(...); // ... // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] ); foreach ($response->iterateAllElements() as $element) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
詳しくは、ライブラリのコンテンツ、アルバム、メディアを一覧表示するをご覧ください。 。
コンテンツ カテゴリ
すべてのメディア アイテムは、処理されてラベルが割り当てられます。特定のキャンペーンを含めたり除外したりできる 次のカテゴリのいずれかに該当します。
ANIMALS |
FASHION |
LANDMARKS |
RECEIPTS |
WEDDINGS |
ARTS |
FLOWERS |
LANDSCAPES |
SCREENSHOTS |
WHITEBOARDS |
BIRTHDAYS |
FOOD |
NIGHT |
SELFIES |
|
CITYSCAPES |
GARDENS |
PEOPLE |
SPORT |
|
CRAFTS |
HOLIDAYS |
PERFORMANCES |
TRAVEL |
|
DOCUMENTS |
HOUSES |
PETS |
UTILITY |
ユーティリティ写真には、幅広いメディアが写っています。一般にこのカテゴリには、ユーザーが特定のタスクを実行するためにキャプチャしたアイテムが含まれます。通常、このようなアイテムはそのタスクが完了したら不要になります。ドキュメント、領収書、スクリーンショット、付箋、メニューなどのメディア アイテムが含まれます。
カテゴリの精度は、 Google フォト商品に間違ったラベルが付けられる可能性もあるため、 コンテンツ カテゴリ フィルタの精度。
カテゴリを含める
複数のカテゴリを指定した場合、指定したカテゴリのいずれかに一致するメディア アイテムが
含まれます。リクエストごとに最大 10 個のカテゴリを指定できます。
この例のフィルタでは、LANDSCAPES
または LANDMARKS
の任意の項目が返されます。
REST
{ "filters": { "contentFilter": { "includedContentCategories": [ "LANDSCAPES", "LANDMARKS" ] } } }
Java
// Create a content filter that includes landmarks and landscapes ContentFilter contentFilter = ContentFilter.newBuilder() .addIncludedContentCategories(ContentCategory.LANDMARKS) .addIncludedContentCategories(ContentCategory.LANDSCAPES) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setContentFilter(contentFilter) .build(); // Specify the Filter object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a content filter that includes landmarks and landscapes $filtersBuilder = new FiltersBuilder(); $filtersBuilder->addIncludedCategory(ContentCategory::LANDMARKS); $filtersBuilder->addIncludedCategory(ContentCategory::LANDSCAPES); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
カテゴリの除外
除外対象として指定したカテゴリのいずれにも一致しないメディア アイテムのみが取得されます。含まれるカテゴリと同様に、最大 10 個のカテゴリを除外できます できます。
以下のフィルタでは、PEOPLE
と SELFIES
のどちらでもないアイテムが返されます。
REST
{ "filters": { "contentFilter": { "excludedContentCategories": [ "PEOPLE", "SELFIES" ] } } }
Java
// Create a content filter that excludes people and selfies ContentFilter contentFilter = ContentFilter.newBuilder() .addExcludedContentCategories(ContentCategory.PEOPLE) .addExcludedContentCategories(ContentCategory.SELFIES) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setContentFilter(contentFilter) .build(); // Specify the Filter object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a content filter that excludes people and selfies $filtersBuilder = new FiltersBuilder(); $filtersBuilder->addExcludedCategory(ContentCategory::PEOPLE); $filtersBuilder->addExcludedCategory(ContentCategory::SELFIES); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
複数のカテゴリの追加と除外
特定のカテゴリを含めたり、他のカテゴリを除外したりできます。次の例をご覧ください。
LANDSCAPES
と LANDMARKS
を返しますが、次を含むメディア アイテムはすべて削除されます
PEOPLE
または SELFIES
の場合:
REST
{ "filters": { "contentFilter": { "includedContentCategories": [ "LANDSCAPES", "LANDMARKS" ], "excludedContentCategories": [ "PEOPLE", "SELFIES" ] } } }
Java
// Create a content filter that excludes people and selfies and includes landmarks and landscapes ContentFilter contentFilter = ContentFilter.newBuilder() .addIncludedContentCategories(ContentCategory.LANDSCAPES) .addIncludedContentCategories(ContentCategory.LANDMARKS) .addExcludedContentCategories(ContentCategory.PEOPLE) .addExcludedContentCategories(ContentCategory.SELFIES) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setContentFilter(contentFilter) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a content filter that excludes people and selfies and includes landmarks and landscapes $filtersBuilder = new FiltersBuilder(); $filtersBuilder->addIncludedCategory(ContentCategory::LANDMARKS); $filtersBuilder->addIncludedCategory(ContentCategory::LANDSCAPES); $filtersBuilder->addExcludedCategory(ContentCategory::PEOPLE); $filtersBuilder->addExcludedCategory(ContentCategory::SELFIES); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
日付と期間
日付フィルタは、返される結果の日付を指定したセットに制限します。 日日付フィルタを指定するには、日付と範囲の 2 つの方法があります。日付と 複数の範囲を組み合わせて使用できます。いずれかの日付または日付に一致するメディア アイテム 範囲が返されます。必要に応じて、結果の並べ替え順を変更できます。
日付
日付には、年、月、日が含まれます。使用できる形式は次のとおりです。
- 年
- 年、月
- 年、月、日
- 月、日
- 月
日付の構成要素が空またはゼロに設定されている場合は、 使用できます。たとえば、年ではなく日と月を設定したと、 任意の年のその月のアイテムをリクエストする場合:
REST
{ "filters": { "dateFilter": { "dates": [ { "month": 2, "day": 15 } ] } } }
Java
// Create a new com.google.type.Date object using a builder // Note that there are different valid combinations as described above Date dayFebruary15 = Date.newBuilder() .setDay(15) .setMonth(2) .build(); // Create a new dateFilter. You can also set multiple dates here DateFilter dateFilter = DateFilter.newBuilder() .addDates(dayFebruary15) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setDateFilter(dateFilter) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new Google\Type\Date object with a day and a month // Note that there are different valid combinations as described above $dateFebruary15 = new Date(); $dateFebruary15->setDay(15); $dateFebruary15->setMonth(2); $filtersBuilder = new FiltersBuilder(); // Add the date to the filter. You can also set multiple dates here $filtersBuilder->addDate($dateFebruary15); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
期間
期間の方が日付よりも柔軟性があります。たとえば、 複数の日付がある場合、期間を使用して、1 か月内の一連の日付を表示できます。
期間には startDate
と endDate
の両方を設定する必要があります。各
リスト内の日付の形式は、
期間。日付は同じ形式にする必要があります。開始日が
終了日も 1 年と 1 か月である必要があります範囲は、
すべてに適用される場合、開始日と終了日は適用されたフィルタに含まれます。
REST
{ "filters": { "dateFilter": { "ranges": [ { "startDate": { "year": 2014, "month": 6, "day": 12 }, "endDate": { "year": 2014, "month": 7, "day": 13 } } ] } } }
Java
// Create new com.google.type.Date objects for two dates Date day2014June12 = Date.newBuilder() .setDay(12) .setMonth(6) .setYear(2014) .build(); Date day2014July13 = Date.newBuilder() .setDay(13) .setMonth(7) .setYear(2014) .build(); // Create a DateRange from these two dates DateRange dateRange = DateRange.newBuilder() .setStartDate(day2014June12) .setEndDate(day2014July13) .build(); // Create a new dateFilter with the date range. You can also set multiple date ranges here DateFilter dateFilter = DateFilter.newBuilder() .addRanges(dateRange) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setDateFilter(dateFilter) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create two new Google\Type\Date objects $date2014June12 = new Date(); $date2014June12->setDay(12); $date2014June12->setMonth(6); $date2014June12->setYear(2014); $date2014July13 = new Date(); $date2014July13->setDay(13); $date2014July13->setMonth(7); $date2014July13->setYear(2014); // Add the two dates as a date range to the filter // You can also set multiple date ranges here $filtersBuilder = new FiltersBuilder(); $filtersBuilder->addDateRange($date2014June12, $date2014July13); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
日付と期間の組み合わせ
複数の日付と複数の期間を同時に使用できます。表示されるアイテム 含まれるものが結果に含まれます。日付と 同じ形式にする必要はありませんが、 次の処理が行われます。
REST
{ "filters": { "dateFilter": { "dates": [ { "year": 2013 }, { "year": 2011, "month": 11 } ], "ranges": [ { "startDate": { "month": 1 }, "endDate": { "month": 3 } }, { "startDate": { "month": 3, "day": 24 }, "endDate": { "month": 5, "day": 2 } } ] } } }
Java
// Create a new com.google.type.Date object for the year 2013 Date day2013 = Date.newBuilder() .setYear(2013) .build(); // Create a new com.google.type.Date object for November 2011 Date day2011November = Date.newBuilder() .setMonth(11) .setYear(2011) .build(); // Create a date range for January to March DateRange dateRangeJanuaryToMarch = DateRange.newBuilder() .setStartDate(Date.newBuilder().setMonth(1).build()) .setEndDate(Date.newBuilder().setMonth(3).build()) .build(); // Create a date range for March 24 to May 2 DateRange dateRangeMarch24toMay2 = DateRange.newBuilder() .setStartDate(Date.newBuilder().setMonth(3).setDay(24).build()) .setEndDate(Date.newBuilder().setMonth(5).setDay(2).build()) .build(); // Create a new dateFilter with the dates and date ranges DateFilter dateFilter = DateFilter.newBuilder() .addDates(day2013) .addDates(day2011November) .addRanges(dateRangeJanuaryToMarch) .addRanges(dateRangeMarch24toMay2) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setDateFilter(dateFilter) .build(); // Specify the Filter object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new Google\Type\Date object for the year 2013 $date2013 = new Date(); $date2013->setYear(2013); // Create a new Google\Type\Date object for November 2011 $dateNovember2011 = new Date(); $dateNovember2011->setMonth(11); $dateNovember2011->setYear(2011); $filtersBuilder = new FiltersBuilder(); // Create a date range for January to March $filtersBuilder->addDateRange((new Date())->setMonth(1), (new Date())->setMonth(3)); // Create a date range for March 24 to May 2 $filtersBuilder->addDateRange((new Date())->setMonth(3)->setDay(24), (new Date())->setMonth(5)->setDay(2)); $filtersBuilder->addDate($date2013); $filtersBuilder->addDate($dateNovember2011); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
メディア アイテムの機能
特徴フィルタを使用すると、検索結果は、特定の特徴を持つアイテムのみに制限されます。 Google フォト アプリでお気に入りとしてマークされた例が表示されます。
お気に入り
次を含める:
FAVORITES
個のアイテム
機能
FeatureFilter
ユーザーがお気に入りとしてマークしたメディア アイテムのみを返す場合:
REST
{ "filters" : { "featureFilter": { "includedFeatures": [ "FAVORITES" ] } } }
Java
// Create a new FeatureFilter for favorite media items FeatureFilter featureFilter = FeatureFilter.newBuilder() .addIncludedFeatures(Feature.FAVORITES) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setFeatureFilter(featureFilter) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new FeatureFilter for favorite media items $filtersBuilder = new FiltersBuilder(); $filtersBuilder->addIncludedFeature(Feature::FAVORITES); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
メディアの種類
写真
PHOTO
は、次のいずれかの画像形式になります。
BMP | JPG |
GIF | PNG |
HEIC | TIFF |
ICO | WebP |
iOS Live Photos、モーション フォト、 360°パノラマ写真、VR 写真です
動画
VIDEO
には、次のようなさまざまな動画形式を使用できます。
3GP | MMV |
3G 2G | MOD |
検索向け AdSense | MOV |
AVI | MP4 |
DivX | マイル / ガロン |
M2T | MTS |
M2TS | TOD |
M4V | WMV |
MKV |
VIDEO
には、VR 動画、
Google フォトで作成されたスローモーション動画、アニメーション
説明します。
次の例では、PHOTO
でフィルタします。
REST
{ "filters": { "mediaTypeFilter": { "mediaTypes": [ "PHOTO" ] } } }
Java
// Create a new MediaTypeFilter for Photo media items MediaTypeFilter mediaType = MediaTypeFilter.newBuilder() .addMediaTypes(MediaType.PHOTO) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setMediaTypeFilter(mediaType) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new MediaTypeFilter for Photo media items $filtersBuilder = new FiltersBuilder(); $filtersBuilder->setMediaType(MediaType::PHOTO); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
複数のメディアタイプのフィルタを組み合わせることはできません。
アーカイブ状態
ユーザーが一部の写真をアーカイブしている可能性があります。デフォルトでは、アーカイブされた写真は 検索結果では返されませんアーカイブ済みのアイテムを含めるには、 次のようにフィルタを設定します。
REST
{ "filters": { "includeArchivedMedia": true } }
Java
// Create a new Filters object that includes archived media Filters filters = Filters.newBuilder() .setIncludeArchivedMedia(true) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new Filters object that includes archived media $filtersBuilder = new FiltersBuilder(); $filtersBuilder->setIncludeArchivedMedia(true); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
フィルタの組み合わせ
さまざまな種類のフィルタを組み合わせることができます。すべての条件に一致するアイテムのみが 返されます。
フィルタを組み合わせる場合、フィルタの種類ごとに形式に関する制限事項は次のとおりです。
個別に使用する場合と同じです。次の例では、写真のみが
SPORT
に分類され、2014 年または 2010 年のデータ
返却:
REST
{ "filters": { "contentFilter": { "includedContentCategories": [ "SPORT" ] }, "dateFilter": { "dates": [ { "year": 2014 }, { "year": 2010 } ] }, "mediaTypeFilter": { "mediaTypes": [ "PHOTO" ] } } }
Java
// Create a new ContentFilter that only includes SPORT items ContentFilter contentFilter = ContentFilter.newBuilder() .addIncludedContentCategories(ContentCategory.SPORT) .build(); // Create a new media type filter that only includes PHOTO media items MediaTypeFilter mediaTypeFilter = MediaTypeFilter.newBuilder() .addMediaTypes(MediaType.PHOTO) .build(); // Create a new DateFilter that only includes items from 2010 or 2014 Date year2014 = Date.newBuilder().setYear(2014).build(); Date year2010 = Date.newBuilder().setYear(2010).build(); DateFilter dateFilter = DateFilter.newBuilder() .addDates(year2010) .addDates(year2014) .build(); // Create a new Filters object combining these filters Filters filters = Filters.newBuilder() .setDateFilter(dateFilter) .setMediaTypeFilter(mediaTypeFilter) .setContentFilter(contentFilter) .build(); // Specify the Filter object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new ContentFilter $filtersBuilder = new FiltersBuilder(); // Only include SPORT items $filtersBuilder->addIncludedCategory(ContentCategory::SPORT); // Only include PHOTO media items $filtersBuilder->setMediaType(MediaType::PHOTO); // Only include items from 2010 or 2014 $year2014 = new Date(); $year2014->setYear(2014); $year2010 = new Date(); $year2010->setYear(2010); $filtersBuilder->addDateRange($year2010, $year2014); // Make a search call with the options set in the filters builder // Filters have been combined in the filter builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
結果の並べ替え
並べ替えることができるのは、日付フィルタを使用したクエリのみです。
並べ替えオプションを指定しない場合、結果は次の順序で並べ替えられます。 降順(新しい順)。
次の表に、orderBy
パラメータでサポートされるオプションを示します。
orderBy パラメータ |
|
---|---|
MediaMetadata.creation_time desc |
メディア アイテムを降順で返します(新しいアイテムが最初)。 |
MediaMetadata.creation_time |
メディア アイテムを昇順(古いアイテムから最初)で返します |
次の例では、2017 年のすべてのメディア アイテムを返し、 新しいものが一番最後になります。
REST
{ "filters": { "dateFilter": { "dates": [ { "year": 2017 } ] } }, "orderBy": "MediaMetadata.creation_time" }
Java
// Create a new dateFilter for the year 2017. DateFilter dateFilter = DateFilter.newBuilder() .addDates(Date.newBuilder().setYear(2017)) .build(); // Create a new Filters object Filters filters = Filters.newBuilder() .setDateFilter(dateFilter) .build(); // Sort results by oldest item first. final OrderBy newestFirstOrder = OrderBy.MEDIAMETADATA_CREATION_TIME; // Specify the filter and sort order in the searchMediaItems call. SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters, newestFirstOrder);
PHP
// Create a new dateFilter for the year 2017. $filtersBuilder = new FiltersBuilder(); $filtersBuilder->addDate((new Date())->setYear(2017)); // Make a search call with the options set in the filters builder and sort // the results by oldest item first. $response = $photosLibraryClient->searchMediaItems( [ 'filters' => $filtersBuilder->build(), 'orderBy' => OrderBy::MEDIAMETADATA_CREATION_TIME ] );