Freigeben über


Verwenden der Microsoft Search-API zum Verfeinern von Abfragen mit Aggregationen

Sie können die Microsoft Search-API in Microsoft Graph verwenden, um Suchergebnisse zu verfeinern und ihre Verteilung im Index anzuzeigen.

Geben Sie zum Verfeinern der Ergebnisse in der SuchanforderungaggregationOption an. Jede aggregationOption gibt die Eigenschaft an, für die die Aggregation berechnet werden soll, und die Anzahl der searchBucket-Elemente , die in der Antwort zurückgegeben werden sollen.

Beispiel 1: Anfordern von Aggregationen nach Zeichenfolgenfeldern

Im folgenden Beispiel werden listItem-Ressourcen durchsucht und ergebnisse nach Dateityp, Inhaltsklasse und Zeitpunkt der letzten Änderung aggregiert, die alle Zeichenfolgenwerte sind.

Die Antwort enthält zwei searchBucket-Objekte für die beiden Aggregationen:

  • Die key-Eigenschaft gibt den tatsächlichen Wert (durch fileType, contentclassoder lastModifiedTime) für die übereinstimmenden listItem-Objekte an, die durch diesen Wert im selben Bucket aggregiert werden.
  • Die count-Eigenschaft gibt die Anzahl solcher Objekte an, die im selben Bucket aggregiert werden. Diese Zahl ist eine Näherung der Anzahl der Übereinstimmungen und liefert keine genaue Anzahl von Übereinstimmungen.
  • Nach Dateityp aggregierte Buckets mit Ergebnissen werden nach Anzahl in absteigender Reihenfolge sortiert. In diesem Beispiel gibt es drei Buckets für 3 Dateitypen: docx, xlsxund pptx.
  • Nach Inhaltsklasse aggregierte Buckets mit Ergebnissen werden nach dem Zeichenfolgenwert der Inhaltsklasse in absteigender Reihenfolge sortiert. In diesem Beispiel gibt es nur einen Bucket mit allen übereinstimmenden Objekten, die dieselbe Inhaltsklasse gemeinsam nutzen: STS_ListItem_DocumentLibrary.
  • Nach lastModifiedTime aggregierte Buckets mit Ergebnissen werden nach dem Zeichenfolgenwert von lastModifiedTime in absteigender Reihenfolge sortiert. Dieses Beispiel enthält drei Buckets: Before 2021-09-01T09:08:19.6224752Z, From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Zund 2021-11-09T09:08:19.6224752Z or later.

Anforderung

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

Antwort

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

Beispiel 2: Anwenden eines Aggregationsfilters basierend auf einer vorherigen Anforderung

In diesem Beispiel wird ein Aggregationsfilter angewendet, der auf dem aggregationFilterToken basiert, das fileType für docx in Beispiel 1 als Feld und From 2021-09-01T09:08:19.6224752Z up to 2021-11-09T09:08:19.6224752Z als lastModifiedTime Feld zurückgegeben wird.

Der der aggregationFilters-Eigenschaft zugewiesene Zeichenfolgenwert hat das Format "{field}:\"{aggregationFilterToken}\". Wenn mehrere Werte für denselben Filter erforderlich sind, sollte der der aggregationFilters-Eigenschaft zugewiesene Zeichenfolgenwert das folgende Format aufweisen: "{field}:or(\"{aggregationFilterToken1}\",\"{aggregationFilterToken2}\")".

Der datetime-formatierungszeichenfolgenwert, der der aggregationFilters-Eigenschaft zugewiesen ist, folgt dem Format "{field}:{aggregationFilterToken}".

Anforderung

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

Antwort

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

Beispiel 3: Anfordern der Aggregation durch ein numerisches Feld

Im folgenden Beispiel werden driveItem-Ressourcen durchsucht und ergebnisse nach ihrer Größe aggregiert, die ein numerischer Wert ist. Die Anforderung gibt die Aggregation nach 3 Größenbereichen an:

  • Größe kleiner als 100
  • Größe zwischen 100 und 1000
  • Größe 1000 und höher

Die Antwort enthält 3 searchBucket-Objekte , eines für jede Größenbereichsaggregation:

  • Die 2 Buckets der niedrigeren Größenbereiche enthalten keine Sucheinstimmungen.
  • Alle 9 Suchbegriffe haben die Größen 1000 oder höher.

Anforderung

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

Antwort

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

Bekannte Einschränkungen

Aggregationen werden nur für SharePoint, OneDrive oder externe Elemente unterstützt. Sie werden für Nachrichten - oder Ereignistypen nicht unterstützt.

Nächste Schritte