ค้นหาและใช้ตัวกรอง

ขอบเขตการให้สิทธิ์ที่จำเป็น

Google Photos Library API มีขอบเขตหลายขอบเขตที่ใช้ในการเข้าถึงรายการสื่อและอัลบั้ม รายการสื่อที่แสดงผลจากการเรียกต่างๆ จะแตกต่างกันไปตามขอบเขตที่นักพัฒนาซอฟต์แวร์ได้ขอ

ขอบเขต photoslibrary.readonly อนุญาตให้เข้าถึงรายการสื่อทั้งหมดในไลบรารีของผู้ใช้ ขอบเขต photoslibrary.readonly.appcreateddata จะอนุญาตการเข้าถึงเฉพาะรายการสื่อที่แอปสร้างขึ้น ดูข้อมูลเพิ่มเติมได้ที่ขอบเขตการให้สิทธิ์

ตัวกรองที่พร้อมใช้งาน

คุณค้นหาสื่อบางประเภทจากคลังของผู้ใช้ได้ เช่น คุณอาจต้องการเฉพาะสิ่งของที่เป็นรูปสัตว์จากวันหนึ่งๆ หรืออาจต้องการไม่รวมรูปภาพใบเสร็จ คุณสามารถยกเว้นหรือรวมบางรายการได้โดยการใช้ตัวกรองกับรายการอัลบั้มหรือคลังเพลง ตัวกรองที่ใช้ได้มี 5 ตัวกรอง ตามคุณสมบัติของรายการสื่อ

ไม่ควรใช้ตัวกรองในคำขอ mediaItems:search หากตั้งค่า albumId ไว้ หากใช้ฟิลเตอร์เมื่อตั้งค่า AlbumsId ระบบจะแสดงข้อผิดพลาด 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 Photos เท่านั้น ในบางครั้ง รายการอาจมีป้ายกำกับที่ไม่ถูกต้อง เราจึงไม่รับประกันความถูกต้องของตัวกรองหมวดหมู่เนื้อหา

รวมหมวดหมู่

เมื่อคุณรวมหลายหมวดหมู่ รายการสื่อที่ตรงกับหมวดหมู่ใดหมวดหมู่หนึ่งจะรวมอยู่ด้วย คุณระบุหมวดหมู่ได้สูงสุด 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()]
);

วันที่และช่วงวันที่

ตัวกรองวันที่จะจำกัดวันที่ของผลลัพธ์ที่แสดงตามชุดวันที่ระบุ การระบุตัวกรองวันที่มี 2 วิธี ได้แก่ วันที่หรือช่วง คุณใช้วันที่และช่วงร่วมกันได้ ระบบจะส่งกลับรายการสื่อที่ตรงกับวันที่หรือช่วงวันที่ใดๆ ลำดับการจัดเรียง จะแก้ไขได้หรือไม่ก็ได้

วันที่

วันที่จะประกอบด้วยปี เดือน และวัน รูปแบบที่ยอมรับมีดังนี้

  • ปี
  • ปี เดือน
  • ปี เดือน วัน
  • เดือน วัน
  • เดือน

หากคอมโพเนนต์ของวันที่ว่างเปล่าหรือตั้งค่าเป็น 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()]
);

ช่วงวันที่

ช่วงวันที่จะให้ความยืดหยุ่นมากกว่าวันที่ เช่น แทนที่จะเพิ่มวันที่หลายวัน คุณสามารถใช้ช่วงวันที่เพื่อดูชุดวันใน 1 เดือนได้

ช่วงวันที่มี 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 Photos

รายชื่อโปรด

ใส่ฟีเจอร์รายการ 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 รูปภาพเคลื่อนไหว พาโนรามา ภาพ 360 องศา และรูปภาพ VR

วิดีโอ

VIDEO อาจเป็นวิดีโอรูปแบบต่างๆ ดังนี้

3GP เกม MMV
3G2 ม็อด
ภาวะ ASF MOV
AVI MP4
DIVX MPG
M2T MTS
M2TS ทอด
M4V WMV
MKV  

VIDEO ยังมีรูปแบบวิดีโอพิเศษอีกด้วย เช่น วิดีโอ VR, วิดีโอสโลว์โมชัน และภาพเคลื่อนไหวที่สร้างขึ้นในแอปพลิเคชัน Google Photos

ตัวอย่างต่อไปนี้กรองตาม 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
    ]
);