Поделиться через


Использование API Microsoft Поиск для уточнения запросов с помощью агрегатов

Api Microsoft Поиск в Microsoft Graph можно использовать для уточнения результатов поиска и отображения их распределения в индексе.

Чтобы уточнить результаты, в поисковом запросе укажите aggregationOption. Каждая функция aggregationOption указывает свойство, по которому должна вычисляться статистическая обработка, и количество элементов searchBucket , возвращаемых в ответе.

Пример 1. Запрос агрегатов по строковым полям

В следующем примере выполняется поиск ресурсов listItem и результаты агрегирования по типу файла, классу содержимого и времени последнего изменения, все из которых являются строковыми значениями.

Ответ включает два объекта searchBucket для двух агрегатов:

  • Свойство key задает фактическое значение (по fileType, contentclassили lastModifiedTime) для тех соответствующих объектов listItem , которые агрегируются в одном контейнере по указанному значению.
  • Свойство count указывает количество таких объектов, объединенных в одном контейнере. Это число является приближенным числом совпадений и не предоставляет точное количество совпадений.
  • Контейнеры результатов, агрегированные по типу файла, сортируются по количеству в порядке убывания. В этом примере имеется 3 контейнера для 3 типов файлов: docx, xlsxи pptx.
  • Контейнеры результатов, агрегированных по классу контента, сортируются по строковому значению класса контента в порядке убывания. В этом примере существует только один контейнер со всеми соответствующими объектами, совместно с которыми используется один и тот же класс содержимого , STS_ListItem_DocumentLibrary.
  • Контейнеры результатов, агрегированные по lastModifiedTime, сортируются по строковому значению lastModifiedTime в порядке убывания. Этот пример включает три контейнера: Before 2021-09-01T09:08:19.6224752Z, From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Zи 2021-11-09T09:08:19.6224752Z or later.

Запрос

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
          "listItem"
      ],
      "query": {
          "queryString": "test"
      },
      "from": 0,
      "size": 25,
      "aggregations": [
          {
              "field": "fileType",
              "size": 20,
              "bucketDefinition": {
                  "sortBy": "count",
                  "isDescending": "true",
                  "minimumCount": 0
              }
          },
          {
              "field": "contentclass",
              "size": 15,
              "bucketDefinition": {
                  "sortBy": "keyAsString",
                  "isDescending": "true",
                  "minimumCount": 0
              }
          },
          {
              "field": "lastModifiedTime",
              "size": 2,
              "bucketDefinition": {
                  "sortBy": "KeyAsString",
                  "isDescending": "true",
                  "minimumCount": 0,
                  "ranges": [
                      {
                          "to": "2021-09-01T09:08:19.6224752Z"
                      },
                      {
                          "from": "2021-09-01T09:08:19.6224752Z",
                          "to": "2021-11-09T09:08:19.6224752Z"
                      },
                      {
                          "from": "2021-11-09T09:08:19.6224752Z"
                      }
                ]
              }
          }
      ]
    }
  ]
}

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.searchResponse",
    "hitsContainers": [
        {
            "@odata.type": "#microsoft.graph.searchHitsContainer",
            "hits": [
                "..."
            ],
            "total": 9,
            "moreResultsAvailable": false,
            "aggregations": [
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "fileType",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "docx",
                            "count": 5,
                            "aggregationFilterToken": "\"ǂǂ646f6378\""
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "xlsx",
                            "count": 3,
                            "aggregationFilterToken": "\"ǂǂ786c7378\""
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "pptx",
                            "count": 1,
                            "aggregationFilterToken": "\"ǂǂ70707478\""
                        }
                    ]
                },
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "contentclass",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "STS_ListItem_DocumentLibrary",
                            "count": 9,
                            "aggregationFilterToken": "\"ǂǂ5354535f4c6973744974656d5f446f63756d656e744c696272617279\""
                        }
                    ]
                },
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "lastModifiedTime",
                    "buckets": [
                        {
                            "key": "Before 2021-09-01T09:08:19.6224752Z",
                            "count": 5,
                            "aggregationFilterToken": "range(min, 2021-09-01T09:08:19.6224752Z)"
                        },
                        {
                            "key": "From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Z",
                            "count": 3,
                            "aggregationFilterToken": "range(2021-09-01T09:08:19.6224752Z, 2021-11-09T09:08:19.6224752Z)"
                        },
                        {
                            "key": "2021-11-09T09:08:19.6224752Z or later",
                            "count": 1,
                            "aggregationFilterToken": "range(2021-11-09T09:08:19.6224752Z, max, to=\"le\")"
                        }
                    ]
                }
            ]
        }
    ]
}

Пример 2. Применение фильтра агрегирования на основе предыдущего запроса

В этом примере применяется фильтр агрегирования, основанный на aggregationFilterToken , возвращенном для docxfileType поля и From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Z в качестве lastModifiedTime поля в примере 1.

Строковое значение, присвоенное свойству aggregationFilters , имеет формат "{field}:\"{aggregationFilterToken}\"". Если для одного фильтра требуется несколько значений, строковое значение, присвоенное свойству aggregationFilters, должно иметь следующий формат: "{field}:or(\"{aggregationFilterToken1}\",\"{aggregationFilterToken2}\")".

Строковое значение формата datetime, присвоенное свойству aggregationFilters, соответствует формату "{field}:{aggregationFilterToken}".

Запрос

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
          "driveItem"
      ],
      "query": {
          "queryString": "test"
      },
      "from": 0,
      "size": 20,
      "aggregations": [
          {
              "field": "fileType",
              "size": 10,
              "bucketDefinition": {
                  "sortBy": "count",
                  "isDescending": "true",
                  "minimumCount": 0
              }
          }
      ],
      "aggregationFilters": [
        "fileType:\"ǂǂ68746d6c\"",
        "lastModifiedTime:range(2021-09-01T09:08:19.6224752Z, 2021-11-09T09:08:19.6224752Z)"
      ]
    }
  ]
}

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.searchResponse",
    "hitsContainers": [
        {
            "@odata.type": "#microsoft.graph.searchHitsContainer",
            "hits": [
                "..."
            ],
            "total": 69960,
            "moreResultsAvailable": true,
            "aggregations": [
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "fileType",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "html",
                            "count": 69960,
                            "aggregationFilterToken": "\"ǂǂ68746d6c\""
                        }
                    ]
                },
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "lastModifiedTime",
                    "buckets": [
                        {
                            "key": "Before 2021-09-01T09:08:19.6224752Z",
                            "count": 0,
                            "aggregationFilterToken": "range(min, 2021-09-01T09:08:19.6224752Z)"
                        },
                        {
                            "key": "From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Z",
                            "count": 69960,
                            "aggregationFilterToken": "range(2021-09-01T09:08:19.6224752Z, 2021-11-09T09:08:19.6224752Z)"
                        },
                        {
                            "key": "2021-11-09T09:08:19.6224752Z or later",
                            "count": 0,
                            "aggregationFilterToken": "range(2021-11-09T09:08:19.6224752Z, max, to=\"le\")"
                        }
                    ]
                }
            ]
        }
    ]
}

Пример 3. Объединение запросов по числовым полям

В следующем примере выполняется поиск ресурсов driveItem и результаты агрегируются по их размеру, что является числовым значением. Запрос задает агрегирование по 3 диапазонам размеров:

  • Размер менее 100
  • Размер от 100 до 1000
  • Размер 1000 и выше

Ответ включает 3 объекта searchBucket , по одному для каждого агрегирования диапазона размеров:

  • 2 контейнера из более низких диапазонов размеров не содержат совпадений поиска.
  • Все 9 совпадений поиска имеют размер 1000 или выше.

Запрос

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "driveItem"
            ],
            "query": {
                "queryString": "test"
            },
            "from": 0,
            "size": 10,
            "aggregations": [
                {
                    "field": "Size",
                    "size": 5,
                    "bucketDefinition": {
                        "sortBy": "keyAsNumber",
                        "isDescending": "true",
                        "minimumCount": 0,
                        "ranges": [
                            {
                                "to": "100"
                            },
                            {
                                "from": "100",
                                "to": "1000"
                            },
                            {
                                "from": "1000"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Отклик

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.searchResponse",
    "hitsContainers": [
        {
            "@odata.type": "#microsoft.graph.searchHitsContainer",
            "hits": [
                "..."
                    ],
            "total": 9,
            "moreResultsAvailable": false,
            "aggregations": [
                {
                    "@odata.type": "#microsoft.substrateSearch.searchAggregation",
                    "field": "Size",
                    "buckets": [
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "Less than 100",
                            "count": 0,
                            "aggregationFilterToken": "range(min, 100)"
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "100 up to 1000",
                            "count": 0,
                            "aggregationFilterToken": "range(100, 1000)"
                        },
                        {
                            "@odata.type": "#microsoft.substrateSearch.searchBucket",
                            "key": "1000 and up",
                            "count": 9,
                            "aggregationFilterToken": "range(1000, max, to=\"le\")"
                        }
                    ]
                }
            ]
        }
    ]
}

Известные ограничения

Агрегаты поддерживаются только для SharePoint, OneDrive или внешних элементов. Они не поддерживаются для типов сообщений или событий .

Дальнейшие действия