本頁面由 Cloud Translation API 翻譯而成。

搜尋及套用篩選器

必要的授權範圍

Google Photos Library API 提供多個範圍，可用於存取媒體項目和相簿。各種呼叫傳回的媒體項目會因開發人員要求的範圍而異。

photoslibrary.readonly 範圍允許存取使用者資料庫中的所有媒體項目。photoslibrary.readonly.appcreateddata 範圍僅允許存取應用程式建立的媒體項目。詳情請參閱「授權範圍」。

可用的篩選器

您可以搜尋使用者的媒體庫，找出特定類型的媒體。舉例來說，您可能只想要動物在特定日期中的項目，或者只想排除收據的相片。您可以對專輯或媒體庫資訊套用篩選器，藉此排除或包含特定項目。根據媒體項目屬性，有五個可用的篩選器：

內容類別 (includedContentCategories、excludedContentCategories)
日期和日期範圍 (dates、ranges)
功能 (featureFilter)
媒體類型 (mediaTypeFilter)
封存狀態 (includeArchivedMedia)

如果已設定 albumId，則不應在 mediaItems:search 要求中使用篩選器。如果在設定 photosId 時使用篩選條件，會傳回 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()]
);

日期和日期範圍

日期篩選器會將傳回結果的日期限制在指定的日期範圍內。指定日期篩選器的方式有兩種：日期或範圍。日期和範圍可以搭配使用。系統會傳回任何符合任一日期或日期範圍的媒體項目。您也可以選擇修改結果的排序順序。

日期

日期包含年、月、日。可接受的格式如下：

年
年，月
年，月，日
月，日
月份

如果日期的元件為空白或設為零，則系統會將其視為萬用字元。舉例來說，如果您設定日期和月份而非年份，就表示該項目是來自任何一年的當天和月份：

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 相簿應用程式中標示為收藏的項目。

常用項目

在 FeatureFilter 中加入 FAVORITES 項目功能，即可只傳回使用者標示為收藏的媒體項目：

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
醫療保健	TIFF
ICO	WEBP

還有特殊的相片類型，例如 iOS 即時相片、動態相片、全景、全景相片和 VR 相片。

影片

VIDEO 可以是多種影片格式：

3 件	MMV (MMV)
3G2	MOD
舊金山	MOV
AVI	MP4
DIVX	英里/加侖
M2T	MTS
M2TS	待辦事項
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
    ]
);