Uso de la API de Microsoft Búsqueda para refinar las consultas con agregaciones

Artículo
03/26/2023

Puede usar microsoft Búsqueda API en Microsoft Graph para refinar los resultados de búsqueda y mostrar su distribución en el índice.

Para refinar los resultados, en la solicitud de búsqueda, especifique aggregationOption. Cada aggregationOption especifica la propiedad en la que se debe calcular la agregación y el número de elementos searchBucket que se devolverán en la respuesta.

Ejemplo 1: Solicitud de agregaciones por campos de cadena

En el ejemplo siguiente se buscan recursos listItem y se agregan los resultados por su tipo de archivo, clase de contenido y hora de última modificación, todos ellos valores de cadena.

La respuesta incluye dos objetos searchBucket para las dos agregaciones:

La propiedad key especifica el valor real (por fileType, contentclasso lastModifiedTime) para los objetos listItem coincidentes agregados en el mismo cubo por ese valor.
La propiedad count especifica el número de objetos agregados en el mismo cubo. Este número es una aproximación del número de coincidencias y no proporcionará un número exacto de coincidencias.
Los cubos de resultados agregados por tipo de archivo se ordenan por recuento en orden descendente. En este ejemplo, hay 3 cubos para 3 tipos de archivo: docx, xlsxy pptx.
Los cubos de resultados agregados por la clase de contenido se ordenan por el valor de cadena de la clase de contenido en orden descendente. En este ejemplo, solo hay un cubo con todos los objetos coincidentes que comparten la misma clase de contenido, STS_ListItem_DocumentLibrary.
Los cubos de resultados agregados por lastModifiedTime se ordenan por el valor de cadena de lastModifiedTime en orden descendente. En este ejemplo se incluyen tres cubos: Before 2021-09-01T09:08:19.6224752Z, From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Zy 2021-11-09T09:08:19.6224752Z or later.

Solicitud

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"
                      }
                ]
              }
          }
      ]
    }
  ]
}

Respuesta

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\")"
                        }
                    ]
                }
            ]
        }
    ]
}

Ejemplo 2: Aplicación de un filtro de agregación basado en una solicitud anterior

En este ejemplo se aplica un filtro de agregación basado en el elemento aggregationFilterToken devuelto para docx como campo fileType y From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Z como campo en el lastModifiedTime ejemplo 1.

El valor de cadena asignado a la propiedad aggregationFilters sigue el formato "{field}:\"{aggregationFilterToken}\". Si se requieren varios valores para el mismo filtro, el valor de cadena asignado a la propiedad aggregationFilters debe seguir este formato: "{field}:or(\"{aggregationFilterToken1}\",\"{aggregationFilterToken2}\")".

El valor de cadena de formato datetime asignado a la propiedad aggregationFilters sigue el formato "{field}:{aggregationFilterToken}".

Solicitud

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)"
      ]
    }
  ]
}

Respuesta

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\")"
                        }
                    ]
                }
            ]
        }
    ]
}

Ejemplo 3: Solicitud de agregación por un campo numérico

En el ejemplo siguiente se buscan recursos driveItem y se agregan resultados por su tamaño que es un valor numérico. La solicitud especifica la agregación en tres intervalos de tamaño:

Tamaño menor que 100
Tamaño entre 100 y 1000
Tamaño 1000 y superior

La respuesta incluye 3 objetos searchBucket , uno para cada agregación de intervalo de tamaño:

Los dos cubos de los intervalos de tamaño inferior no incluyen ninguna coincidencia de búsqueda.
Las 9 coincidencias de búsqueda tienen tamaños de 1000 o superior.

Solicitud

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"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Respuesta

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\")"
                        }
                    ]
                }
            ]
        }
    ]
}

Limitaciones conocidas

Las agregaciones solo se admiten para SharePoint, OneDrive o elementos externos. No se admiten para los tipos de mensaje o evento .

Pasos siguientes

Empleo de la API de Búsqueda de Microsoft para consultar datos

Compartir a través de

Uso de la API de Microsoft Búsqueda para refinar las consultas con agregaciones

Ejemplo 1: Solicitud de agregaciones por campos de cadena

Solicitud

Respuesta

Ejemplo 2: Aplicación de un filtro de agregación basado en una solicitud anterior

Solicitud

Respuesta

Ejemplo 3: Solicitud de agregación por un campo numérico

Solicitud

Respuesta

Limitaciones conocidas

Pasos siguientes

Comentarios

Recursos adicionales