Utiliser l’API Microsoft Recherche pour affiner les requêtes avec des agrégations

  • Article

Vous pouvez utiliser l’API Microsoft Recherche dans Microsoft Graph pour affiner les résultats de recherche et afficher leur distribution dans l’index.

Pour affiner les résultats, dans la demande de recherche, spécifiez l’option aggregationOption. Chaque aggregationOption spécifie la propriété sur laquelle l’agrégation doit être calculée et le nombre d’éléments searchBucket à retourner dans la réponse.

Exemple 1 : Demander des agrégations par champs de chaîne

L’exemple suivant recherche les ressources listItem et agrège les résultats par type de fichier, classe de contenu et heure de la dernière modification, qui sont tous des valeurs de chaîne.

La réponse inclut deux objets searchBucket pour les deux agrégations :

  • La propriété key spécifie la valeur réelle (par fileType, contentclassou lastModifiedTime) pour les objets listItem correspondants qui sont agrégés dans le même compartiment par cette valeur.
  • La propriété count spécifie le nombre d’objets de ce type agrégés dans le même compartiment. Ce nombre est une approximation du nombre de correspondances et ne fournit pas de nombre exact de correspondances.
  • Les compartiments de résultats agrégés par type de fichier sont triés par nombre dans l’ordre décroissant. Dans cet exemple, il existe 3 compartiments pour 3 types de fichiers : docx, xlsxet pptx.
  • Les compartiments de résultats agrégés par classe de contenu sont triés par la valeur de chaîne de la classe de contenu dans l’ordre décroissant. Dans cet exemple, il n’existe qu’un seul compartiment avec tous les objets correspondants partageant la même classe de contenu, STS_ListItem_DocumentLibrary.
  • Les compartiments de résultats agrégés par lastModifiedTime sont triés par la valeur de chaîne de lastModifiedTime dans l’ordre décroissant. Cet exemple inclut trois compartiments : Before 2021-09-01T09:08:19.6224752Z, From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Zet 2021-11-09T09:08:19.6224752Z or later.

Demande

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

Réponse

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

Exemple 2 : Appliquer un filtre d’agrégation basé sur une requête précédente

Cet exemple applique un filtre d’agrégation basé sur l’objet aggregationFilterToken retourné comme docxfileType champ et From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Z comme champ dans l’exemple lastModifiedTime 1.

La valeur de chaîne affectée à la propriété aggregationFilters suit le format « {field} :\"{aggregationFilterToken}\" ». Si plusieurs valeurs pour le même filtre sont requises, la valeur de chaîne affectée à la propriété aggregationFilters doit suivre le format suivant : « {field} :or(\"{aggregationFilterToken1}\ »,\"{aggregationFilterToken2}\ ») ».

La valeur de chaîne de mise en forme datetime affectée à la propriété aggregationFilters suit le format « {field} :{aggregationFilterToken} ».

Demande

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

Réponse

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

Exemple 3 : Demander l’agrégation par un champ numérique

L’exemple suivant recherche les ressources driveItem et agrège les résultats en fonction de leur taille, qui est une valeur numérique. La requête spécifie l’agrégation par 3 plages de tailles :

  • Taille inférieure à 100
  • Taille comprise entre 100 et 1000
  • Taille 1000 et supérieure

La réponse comprend 3 objets searchBucket , un pour chaque agrégation de plages de tailles :

  • Les 2 compartiments des plages de tailles inférieures n’incluent aucune correspondance de recherche.
  • Les 9 correspondances de recherche ont des tailles supérieures ou supérieures à 1 000.

Demande

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

Réponse

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

Limitations connues

Les agrégations sont prises en charge uniquement pour SharePoint, OneDrive ou les éléments externes. Ils ne sont pas pris en charge pour les types de messages ou d’événements .

Étapes suivantes