必要的授權範圍
Google Photos Library API 包含多個範圍,可用於存取媒體項目和相簿。 根據不同的範圍,各種呼叫傳回的媒體項目會有所不同 未獲得開發人員的要求
photoslibrary.readonly 範圍允許存取
使用者的程式庫。photoslibrary.readonly.appcreateddata 範圍允許存取
只會用於由應用程式建立的媒體項目若需更多資訊,請參閲
授權範圍。
可用的篩選器
您可在使用者的媒體庫中搜尋特定類型的媒體,舉例來說, 您可能只想尋找動物造型、特定日期的物品 排除收據的相片。您可以用下列方式排除或加入特定項目: 正在將篩選器套用至相簿或相片庫清單。這裡有五個 會根據媒體項目屬性進行篩選:
- 內容類別 (
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()] );
日期和日期範圍
日期篩選器會將傳回結果的日期限制為一組指定的 天。有兩種方法可指定日期篩選器:日期篩選器。日期和 範圍可能會一起使用符合任一日期或日期的媒體項目 範圍。視需求選擇結果排序順序。 可以修改。
日期
日期包含年、月和日。我們接受以下格式:
- 年
- 年,月
- 年,月,日
- 月/日
- 月
如果日期部分為空白或設為 0,系統會視為 萬用字元。舉例來說,如果您設定了日期和月份,但不設定年份,就表示您的 要求特定日期和月份中的項目:
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()] );
日期範圍
日期範圍比日期更有彈性。舉例來說 多個日期,日期範圍可用來查看一個月內的一組天數。
日期範圍包含 startDate 和 endDate,兩者皆須設定。每項
範圍中的日期與
日期:日期格式必須相同:如果開始日期是
月份和月份時,結束日期也必須為年份和月份。範圍是
套用的篩選器會包含開始和結束日期:
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 即時相片、動態相片等特殊相片類型。 全景、全景相片和 VR 相片。
影片
VIDEO 可以是各種影片格式:
| 3GP | MMV |
| 3G2 | MOD |
| ASF | MOV |
| AVI | MP4 |
| DIVX | 油耗 (MPG) |
| 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()] );
無法合併多個媒體類型篩選器。
排除非應用程式建立的資料
如要排除未由應用程式建立的媒體項目,您可以設定
excludeNonAppCreatedData 篩選器,如以下範例所示:
REST
{
"filters": {
"excludeNonAppCreatedData": true
}
}Java
// Create a new Filters object that excludes media not created by your app Filters filters = Filters.newBuilder() .setExcludeNonAppCreatedData(true) .build(); // Specify the Filters object in the searchMediaItems call SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(filters);
PHP
// Create a new Filters object that excludes media not created by your app $filtersBuilder = new FiltersBuilder(); $filtersBuilder->setExcludeNonAppCreatedData(true); // Make a search call with the options set in the filters builder $response = $photosLibraryClient->searchMediaItems( ['filters' => $filtersBuilder->build()] );
請注意,如果您使用
.readonly.appcreateddata敬上
範圍內,這個篩選器就會被忽略。
封存狀態
您的使用者可能封存了部分相片。根據預設,已封存的相片 而不會傳回搜尋結果。如要納入已封存的項目,可以在 篩選器,如以下範例所示:
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 ] );