- HTTP 要求
- 要求主體
- 回應主體
- 授權範圍
- 濾鏡
- DateFilter
- 日期
- DateRange
- ContentFilter
- ContentCategory
- MediaTypeFilter
- MediaType
- FeatureFilter
- 功能
- 試試看!
在使用者的 Google 相簿相片庫中搜尋媒體項目。如果未設定篩選器,系統會傳回使用者媒體庫中的所有媒體項目。設定相簿後,系統會傳回指定相簿中的所有媒體項目。如果指定篩選器,系統會列出使用者媒體庫中符合篩選器的媒體項目。如果同時設定相簿和篩選器,要求會導致錯誤。
HTTP 要求
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{
"albumId": string,
"pageSize": integer,
"pageToken": string,
"filters": {
object ( |
欄位 | |
---|---|
albumId |
相簿的 ID。如果填入,則會列出指定相簿中的所有媒體項目。無法與任何篩選器搭配使用。 |
pageSize |
回應中傳回的媒體項目數量上限。可能傳回的媒體項目數量可能少於指定數量。預設 |
pageToken |
用於取得結果下一頁的接續權杖。將此項目加入要求,會傳回 |
filters |
套用至要求的篩選器。無法與 |
orderBy |
選用欄位,用於指定搜尋結果的排序順序。 可搭配這個參數使用的唯一篩選器是 |
回應主體
符合搜尋參數的媒體項目清單。
如果成功,回應主體會含有以下結構的資料:
JSON 表示法 |
---|
{
"mediaItems": [
{
object ( |
欄位 | |
---|---|
mediaItems[] |
僅供輸出。與搜尋參數相符的媒體項目清單。 |
nextPageToken |
僅供輸出。使用這個權杖取得下一組媒體項目。只有這項屬性可可靠地指出下一個要求中會有更多媒體項目。 |
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/photoslibrary
https://www.googleapis.com/auth/photoslibrary.readonly
https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
篩選器
可套用至媒體項目搜尋的篩選器。如果指定多個篩選器選項,它們會彼此視為 AND。
JSON 表示法 |
---|
{ "dateFilter": { object ( |
欄位 | |
---|---|
dateFilter |
根據媒體項目的建立日期篩選媒體項目。 |
contentFilter |
根據媒體項目的內容進行篩選。 |
mediaTypeFilter |
根據媒體類型篩選媒體項目。 |
featureFilter |
根據媒體項目的功能篩選媒體項目。 |
includeArchivedMedia |
設定後,結果會包含使用者封存的媒體項目。預設值為 false (不包含已封存的媒體項目)。 |
excludeNonAppCreatedData |
設定後,結果會排除不是由這個應用程式建立的媒體項目。預設值為 false (傳回所有媒體項目)。如果使用 photoslibrary.readonly.appcreateddata 範圍,系統會略過這個欄位。 |
DateFilter
這個篩選器可為傳回的媒體定義允許的日期或日期範圍。您可以選取一組特定日期和日期範圍。如果上傳的媒體項目沒有指定擷取媒體項目日期的中繼資料,就無法透過日期篩選器在查詢中傳回。在這種情況下,系統不會使用 Google 相簿伺服器的上傳時間做為備用。
JSON 表示法 |
---|
{ "dates": [ { object ( |
欄位 | |
---|---|
dates[] |
與媒體項目相符的日期清單建立日期。每項要求最多可加入 5 個日期。 |
ranges[] |
與媒體項目相符的日期範圍清單建立日期。每項要求最多可加入 5 個日期範圍。 |
日期
代表整個日曆的日期。如果只有月份和年份都很重要,例如是 2018 年 12 月,請將 day
設為 0。如果只有重要的年份 (例如整個 2018 年),請將 day
和 month
設為 0。如果只有「日」和「生日」是重要時 (例如週年或生日),請將 year
設為 0。
不支援:將所有值設為 0、僅將 month
設為 0,或同時將 day
和 year
同時設為 0。
JSON 表示法 |
---|
{ "year": integer, "month": integer, "day": integer } |
欄位 | |
---|---|
year |
日期的年份。這個值必須介於 1 至 9999,或 0 之間可指定不含年份的日期。 |
month |
一年中的月份。必須介於 1 到 12 之間,或 0 可以指定不含月份和日期的年份。 |
day |
日期。必須介於 1 到 31 之間,且有效的年份和月份;如果指定不重要的年/月,則為 0。 |
DateRange
用於定義日期範圍。兩個日期的格式必須相同。詳情請參閱 Date
。
JSON 表示法 |
---|
{ "startDate": { object ( |
欄位 | |
---|---|
startDate |
以上述任一格式指定的開始日期 (包含在日期範圍中)。 |
endDate |
結束日期 (包含在範圍中)。指定格式時,必須採用與開始日期相同的格式。 |
ContentFilter
這個篩選器可讓您依據內容類型傳回媒體項目。
您可以指定要包含的類別清單和/或要排除的類別清單,每份清單中的類別會以 OR 符號合併。
內容篩選器 includedContentCategories
:[c1, c2, c3] 會取得含有 (c1 OR c2 OR c3) 的媒體項目。
內容篩選器 excludedContentCategories
: [c1, c2, c3] 不會取得含有 (c1 OR c2 OR c3) 的媒體項目,
您也可以加入某些類別,但排除其他類別,例如:includedContentCategories
:[c1, c2]、excludedContentCategories
:[c3, c4]
上一個範例會取得包含 (c1 OR c2) AND NOT (c3 OR c4) 的媒體項目。includedContentategories
中顯示的類別不得出現在 excludedContentCategories
中。
JSON 表示法 |
---|
{ "includedContentCategories": [ enum ( |
欄位 | |
---|---|
includedContentCategories[] |
要納入媒體項目搜尋結果的類別組合。組合中的項目會以 OR 方式處理。每項要求最多有 10 個 |
excludedContentCategories[] |
不應納入媒體項目搜尋結果的類別組合。集合中的項目會以 OR 運算,每項要求最多有 10 個 |
ContentCategory
這是一組預先定義的內容類別,可供您做為篩選依據。
列舉 | |
---|---|
NONE |
預設內容類別。如果篩選器中使用其他類別,系統就會忽略這個類別。 |
LANDSCAPES |
包含橫向的媒體項目。 |
RECEIPTS |
包含收據的媒體項目。 |
CITYSCAPES |
包含城市景觀的媒體項目。 |
LANDMARKS |
含有地標的媒體項目。 |
SELFIES |
自拍媒體項目。 |
PEOPLE |
包含人物的媒體項目。 |
PETS |
包含寵物的媒體項目。 |
WEDDINGS |
婚禮媒體項目。 |
BIRTHDAYS |
生日的媒體項目。 |
DOCUMENTS |
包含文件的媒體項目。 |
TRAVEL |
在旅遊期間拍攝的媒體項目。 |
ANIMALS |
包含動物的媒體項目。 |
FOOD |
包含食物的媒體項目。 |
SPORT |
運動賽事的媒體項目。 |
NIGHT |
在夜間拍攝的媒體項目。 |
PERFORMANCES |
用於表演的媒體項目。 |
WHITEBOARDS |
包含白板的媒體項目。 |
SCREENSHOTS |
螢幕截圖的媒體項目。 |
UTILITY |
媒體項目被視為實用工具。包括但不限於文件、螢幕截圖和白板等。 |
ARTS |
包含圖片的媒體項目。 |
CRAFTS |
包含手工藝的媒體項目。 |
FASHION |
與時尚相關的媒體項目。 |
HOUSES |
包含房屋的媒體項目。 |
GARDENS |
包含花園的媒體項目。 |
FLOWERS |
包含花朵的媒體項目。 |
HOLIDAYS |
節日的媒體項目。 |
MediaTypeFilter
這個篩選器可定義要傳回的媒體項目類型,例如影片或相片。僅支援一種媒體類型。
JSON 表示法 |
---|
{
"mediaTypes": [
enum ( |
欄位 | |
---|---|
mediaTypes[] |
要納入的媒體項目類型。這個欄位只能填入一種媒體類型,如果您指定多個媒體類型,就會發生錯誤。 |
MediaType
可搜尋的媒體類型組合。
列舉 | |
---|---|
ALL_MEDIA |
視為未套用任何篩選器。包含所有媒體類型。 |
VIDEO |
所有視為影片的媒體項目。這也包括使用者使用 Google 相簿應用程式建立的電影。 |
PHOTO |
視為相片的所有媒體項目。包括 .bmp、.gif、.ico、.jpg (和其他拼寫方式)、.tiff、.webp 和特殊相片類型,例如 iOS 動態相片、Android 動態相片、全景相片、全景相片。 |
FeatureFilter
這個篩選器定義了媒體項目應具備的功能。
JSON 表示法 |
---|
{
"includedFeatures": [
enum ( |
欄位 | |
---|---|
includedFeatures[] |
要納入媒體項目搜尋結果的一組功能。集合中的項目會經過 OR 處理,且可能會符合任何指定的地圖項目。 |
功能
可用來篩選的功能組合。
列舉 | |
---|---|
NONE |
系統會視為未套用任何篩選器。包含所有功能。 |
FAVORITES |
使用者在 Google 相簿應用程式中標示為收藏的媒體項目。 |