البحث عن الفلاتر وتطبيقها

نطاقات التفويض المطلوبة

تحتوي واجهة برمجة التطبيقات لمكتبة "صور Google" على نطاقات متعددة تُستخدم للوصول إلى ملفات الوسائط والألبومات. تختلف عناصر الوسائط التي يتم عرضها من الاتصالات المختلفة بناءً على النطاقات التي طلبها المطوّر.

يسمح نطاق photoslibrary.readonly بالوصول إلى جميع عناصر الوسائط في مكتبة المستخدم. يتيح نطاق photoslibrary.readonly.appcreateddata الوصول فقط إلى عناصر الوسائط التي أنشأها التطبيق. لمزيد من المعلومات، يمكنك الاطّلاع على نطاقات التفويض.

الفلاتر المتوفرة

يمكنك البحث في مكتبة المستخدم عن أنواع محدّدة من الوسائط. على سبيل المثال، قد ترغب فقط في العناصر التي هي من الحيوانات، من يوم معين، أو قد ترغب في استبعاد صور الإيصالات. يمكنك استبعاد عناصر معينة أو تضمينها عن طريق تطبيق عوامل التصفية على بطاقة بيانات ألبوم أو مكتبة. تتوفر خمسة فلاتر استنادًا إلى خصائص عنصر الوسائط:

يجب عدم استخدام الفلاتر في طلب mediaItems:search إذا تم ضبط albumId. في حال استخدام فلتر عند ضبط albumId، سيتم عرض خطأ INVALID_ARGUMENT (400).

يتم ترتيب النتائج حسب وقت إنشاء عنصر الوسائط. يمكن تعديل ترتيب الترتيب لطلبات البحث باستخدام فلاتر التاريخ.

انتظر بعض الوقت لتظهر الوسائط التي تم تحميلها مؤخرًا في عمليات البحث. تظهر الوسائط في عمليات بحث لم تتم تصفيتها على الفور.

ولا تظهر عناصر الوسائط التي لها تاريخ في المستقبل في عمليات البحث التي تمت فلترتها. وتظهر في عمليات البحث التي لم تتم فلترتها وعمليات بحث الألبومات.

تطبيق فلتر

لتطبيق فلتر، عليك استدعاء mediaItems.search وتحديد السمة filter.

راحة

إليك طلب 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.

راحة

{
  "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:

راحة

{
  "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:

راحة

{
  "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()]
);

التواريخ والنطاقات الزمنية

تقيد فلاتر التاريخ تاريخ النتائج المعروضة بمجموعة محددة من الأيام. هناك طريقتان لتحديد فلتر تاريخ: التواريخ أو النطاقات. يمكن استخدام التواريخ والنطاقات معًا. يتم إرجاع عناصر الوسائط التي تطابق أيًا من التواريخ أو النطاقات الزمنية. بشكل اختياري، يمكن تعديل ترتيب النتائج للنتائج.

التواريخ

يحتوي التاريخ على سنة وشهر ويوم. التنسيقات التالية مقبولة:

  • Year
  • السنة، الشهر
  • السنة، الشهر، اليوم
  • شهر، يوم
  • الشهر

عندما يكون أحد مكونات التاريخ فارغًا أو تم ضبطه على صفر، يتم التعامل معه على أنّه حرف بدل. على سبيل المثال، إذا حددت اليوم والشهر، ولكن ليس العام، فأنت تطلب عناصر من ذلك اليوم والشهر من أي عام:

راحة

{
  "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، ويجب ضبط كلتا القيمتين. لكل تاريخ في النطاق قيود التنسيق نفسها كما هو موضّح في التواريخ. يجب أن يكون للتواريخ التنسيق نفسه: إذا كان تاريخ البدء سنة وشهر، فيجب أن يكون تاريخ الانتهاء أيضًا سنة وشهر. يتم تطبيق النطاقات بشكل شامل، يتم تضمين تاريخي البدء والانتهاء في الفلتر المطبق:

راحة

{
  "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()]
    );

دمج التواريخ والنطاقات الزمنية

يمكنك استخدام تواريخ متعدّدة ونطاقات زمنية متعدّدة في الوقت نفسه. يتم تضمين العناصر التي تقع ضمن أي من هذه التواريخ في النتائج. لا تحتاج التواريخ والنطاقات الزمنية المنفصلة إلى اتباع التنسيق نفسه، لكن تواريخ البدء والانتهاء للنطاقات الفردية تنطبق على ما يلي:

راحة

{
  "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".

الأجهزة المفضَّلة

يمكنك تضمين ميزة FAVORITES للسلعة في FeatureFilter لعرض عناصر الوسائط التي وضع المستخدم علامة عليها كعناصر مفضّلة فقط:

راحة

{
  "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 درجة وصور الواقع الافتراضي.

حملة فيديو

يمكن أن يكون عنصر "VIDEO" بتنسيقات مختلفة للفيديو:

3GP MMV
شبكة الجيل الثاني تعديل
ASF MOV
AVI MP4
سجل DIVX ميل/غالون
M2T MTS
خدمة M2TS TOD
فيديو M4V WMV
MKV  

يتضمن VIDEO أيضًا تنسيقات خاصة للفيديوهات، مثل ما يلي: فيديوهات الواقع الافتراضي، والفيديوهات البطيئة، والرسوم المتحركة التي يتم إنشاؤها في تطبيق "صور Google".

في ما يلي مثال للفلاتر حسب PHOTO:

راحة

{
  "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 كما هو موضّح في المثال التالي:

راحة

{
  "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، يتم تجاهل هذا الفلتر.

حالة الأرشفة

ربما أرشف المستخدمون بعض صورهم. حسب الإعدادات التلقائية، لا يتم عرض الصور المؤرشفة في عمليات البحث. لتضمين العناصر المؤرشفة، يمكنك وضع علامة في الفلتر كما هو موضح في المثال التالي:

راحة

{
  "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:

راحة

{
  "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، ويعرض الأقدم أولاً والأحدث وأخيرًا.

راحة

{
  "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
    ]
);