- 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 之間;如要指定不含月和日的年份,請輸入 1 至 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[] |
要納入媒體項目搜尋結果的類別組合。組合中的項目會以「或」方式呈現。每個要求最多只能有 10 個 |
excludedContentCategories[] |
不會納入媒體項目搜尋結果的一組類別。組合中的項目會以「或」方式呈現。每個要求最多只能有 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 相簿應用程式中標示為收藏的媒體項目。 |