- HTTP 要求
- 要求主體
- 回應主體
- 授權範圍
- 篩選器
- DateFilter
- 日期
- 日期範圍
- 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 範圍,系統就會忽略這個欄位。 |
日期篩選器
這個篩選器定義了傳回媒體允許的日期範圍或日期範圍。您可以挑選一組特定日期和一組日期範圍。如果上傳的媒體項目未指定中繼資料的擷取日期,就不會在使用日期篩選器的查詢中傳回媒體項目。在這種情況下,Google 相簿伺服器上傳時間不會做為備用。
JSON 表示法 |
---|
{ "dates": [ { object ( |
欄位 | |
---|---|
dates[] |
與媒體項目建立日期相符的日期清單。每個要求最多可包含 5 個日期。 |
ranges[] |
與媒體項目建立日期相符的日期範圍清單。每個要求最多可包含 5 個日期範圍。 |
日期
代表整個日曆的日期。當只有重要月份和年份時,請將 day
設為 0,例如 2018 年 12 月。如果只有重要年份 (例如整個 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。 |
日期範圍
用於定義日期範圍。兩個日期必須採用相同格式。詳情請參閱 Date
。
JSON 表示法 |
---|
{ "startDate": { object ( |
欄位 | |
---|---|
startDate |
以上述其中一種格式顯示的開始日期 (在日期範圍範圍內)。 |
endDate |
結束日期 (在日期範圍範圍內)。指定的格式必須與開始日期相同。 |
內容篩選器
這個篩選器可讓您根據內容類型傳回媒體項目。
您可以指定要納入的類別清單和/或要排除的類別清單。因此,每個清單中的類別都會以 OR 連結。
內容篩選器 includedContentCategories
:[c1, c2, c3] 會取得包含 (c1 OR c2 或 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 個 |
內容類別
這組預先定義的內容類別可供篩選。
列舉 | |
---|---|
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 |
節日拍攝的媒體項目。 |
媒體類型篩選器
這個篩選器會定義要傳回的媒體項目類型,例如影片或相片。系統僅支援一種媒體類型,
JSON 表示法 |
---|
{
"mediaTypes": [
enum ( |
欄位 | |
---|---|
mediaTypes[] |
要納入的媒體項目類型。這個欄位只能填入一種媒體類型。如果指定多個媒體類型,就會發生錯誤。 |
MediaType
可供搜尋的媒體類型組合。
列舉 | |
---|---|
ALL_MEDIA |
視為未套用篩選器。包含所有媒體類型。 |
VIDEO |
所有屬於影片的媒體項目。使用者使用 Google 相簿應用程式製作的電影也包括在內。 |
PHOTO |
所有屬於相片的媒體項目。包括 .bmp、.gif、.ico、.jpg (和其他拼寫)、.tiff、.webp 和特殊相片類型 (例如 iOS 實景相片、Android 動態相片、全景相片、全景相片)。 |
特徵篩選器
這個篩選器定義了媒體項目應具備的功能。
JSON 表示法 |
---|
{
"includedFeatures": [
enum ( |
欄位 | |
---|---|
includedFeatures[] |
要納入媒體項目搜尋結果的一組功能。組合中的項目以 OR 表示,並可能符合任何指定的地圖項目。 |
特徵
可供篩選的功能組合。
列舉 | |
---|---|
NONE |
視為未套用篩選器。具備所有功能。 |
FAVORITES |
使用者在 Google 相簿應用程式中標示為收藏的媒體項目。 |