Feedback Bearbeiten

Verwendung der Microsoft Search-API zum Abfragen von Daten

  • Artikel
  • 8 Minuten Lesedauer

Sie können die Microsoft Search-API verwenden, um Microsoft 365-Daten in Ihren Apps abzufragen.

Suchanforderungen werden im Kontext des angemeldeten Benutzers ausgeführt, wobei die Identifizierung über ein Zugriffstoken mit delegierten Berechtigungen erfolgt.

Allgemeine Anwendungsfälle

Die Microsoft Search-API stellt eine Abfrage-Methode zum Durchsuchen Ihrer Daten in Microsoft Search bereit, in der Sie eine searchRequest im Anforderungstext übergeben und die Spezifik Ihrer Suche definieren.

In diesem Abschnitt werden die allgemeinen Anwendungsfälle der Abfrage-Methode aufgelistet, basierend auf den Eigenschaften und Parametern, die Sie im searchRequest-Textkörper der Abfrage festgelegt haben.

Die Suchanforderungen werden im Namen des Benutzers ausgeführt. Die Suchergebnisse werden so festgelegt, um alle auf die Elemente angewendeten Zugriffskontrollen zu erzwingen. Im Kontext von Dateien werden beispielsweise die Berechtigungen für die Dateien als Teil der Suchanforderung ausgewertet. Benutzer können bei einer Suche nicht auf mehr Elemente zugreifen, als sie sonst bei einer entsprechenden GET-Operation mit den gleichen Berechtigungen und der gleichen Zugriffskontrolle erhalten können.

Anwendungsfälle Eigenschaften, die im Text der Abfrageanforderung definiert werden sollen
Bereich der Suchtergebnisse auf Grundlage von Entitätstypen festlegen entityTypes
Seitenergebnisse von und Größe
Abrufen der relevantesten E-Mails enableTopResults
Ausgewählte Eigenschaften abrufen Feldern
Verwenden von KQL in Abfragebedingungen query
Suchergebnisse sortieren sort
Verfeinern von Ergebnissen mithilfe von Aggregationen aggregations
Rechtschreibkorrektur anfordern queryAlterationOptions
Anzeige-Layout durchsuchen (Vorschau) resultTemplateOptions

Bereichssuche auf Grundlage von Entitätstypen

Definieren Sie den Umfang der Suchanforderung mithilfe der entityTypes-Eigenschaft in der query-Anforderungsnutzlast. In der folgenden Tabelle werden die für die Abfrage verfügbaren Typen sowie die unterstützten Berechtigungen für den Zugriff auf die Daten beschrieben.

EntityType Für den Zugriff auf die Elemente erforderlicher Berechtigungsbereich Source Kommentar
meldung Mail.Read, Mail.ReadWrite Exchange Online E-Mail-Nachrichten.
event Calendars.Read, Calendars.ReadWrite Exchange Online Kalenderereignisse.
drive Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint Mithilfe von Dokumentbibliotheken.
driveItem Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All SharePoint und OneDrive Dateien, Ordner, Seiten und Nachrichten.
list Sites.Read.All, Sites.ReadWrite.All SharePoint und OneDrive Listen. Beachten Sie, dass Dokumentbibliotheken auch als Listen zurückgegeben werden.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint und OneDrive Elemente auflisten. Beachten Sie, dass Dateien und Ordner auch als Listenelemente zurückgegeben werden. listItem ist die übergeordnete Klasse von driveItem.
site Sites.Read.All, Sites.ReadWrite.All SharePoint Websites in SharePoint.

Seitensuchergebnisse

Legen Sie die Paginierung der Suchergebnisse fest, indem Sie die beiden folgenden Eigenschaften im query-Anforderungstext angeben:

  • aus ‑ Eine ganze Zahl, die den 0-basierten Ausgangspunkt angibt, um die Suchergebnisse auf der Seite aufzulisten. Der Standardwert ist 0.

  • Größe ‑ Eine ganze Zahl, welche die Anzahl der für eine Seite zurückzugebenden Ergebnisse angibt. Der Standardwert ist 25 Ergebnisse. Der Höchstwert beträgt 1.000 Ergebnisse.

Beachten Sie die folgenden Einschränkungen, wenn Sie die Entität event oder message durchsuchen:

  • aus muss bei der ersten Seitenanforderung mit Null beginnen, andernfalls führt die Anforderung zu HTTP 400 Bad request.
  • Die maximale Anzahl von Ergebnissen pro Seite (Größe) beträgt 25 für Nachrichten und Ereignisse.

Es gibt keine Obergrenze für SharePoint- oder OneDrive-Elemente. Ein vernünftiges Seitenformat ist 200. Ein größeres Seitenformat verursacht im Allgemeinen eine höhere Latenz.

Bewährte Methoden:

  • Geben Sie in der anfänglichen Anforderung eine kleinere erste Seite an. Geben Sie beispielsweise von als 0 und Größe als 25 an.

  • Paginieren Sie die nachfolgenden Seiten, indem Sie die Eigenschaften von und Größe aktualisieren. Sie können das Seitenformat in jeder nachfolgenden Anforderung vergrößern. Die folgende Tabelle zeigt ein Beispiel.

    Seite von Größe
    1 0 25
    2 25 50
    3 75 75
    4 150 100

Abrufen der relevantesten E-Mails

Beim Durchsuchen der Entität message wird durch Angabe von enableTopResults als true eine Hybridliste von Nachrichten zurückgegeben: die ersten 3 Nachrichten in der Antwort sind nach Relevanz sortiert, die verbleibenden Nachrichten werden nach Datum/ Uhrzeit sortiert.

Ausgewählte Eigenschaften abrufen

Wenn Sie einen Entitätstyp durchsuchen, z. B. message, event, drive, driveItem, list, listItem, site, externalItem, können Sie in die fields-Eigenschaft spezifische Entitätseigenschaften einschließen, die in den Suchergebnissen zurückgegeben werden sollen. Dies ähnelt der Verwendung der Option OData-Systemabfragenoption, $select in REST-Aufträgen. Die Such-API unterstützt diese Abfrageoptionen technisch nicht, da das Verhalten im POST-Textkörper angegeben ist.

Bei allen diesen Entitätstypen wird durch die Angabe der fields-Eigenschaft die Anzahl der in der Antwort zurückgegebenen Eigenschaften verringert, wodurch die Nutzlast über die Leitung optimiert wird.

Die listItem- und externalItem-Entitäten sind die einzigen unterstützten Entitäten, die das übernehmen von erweiterten abrufbaren Feldern im Schema zulassen. Sie können keine erweiterten Eigenschaften aus allen anderen Entitäten unter Verwendung der Such-API abrufen. Wenn Sie beispielsweise ein abrufbares Feld für externalItem im Suchschema erstellt haben oder wenn Sie eine abrufbare benutzerdefinierte Spalte in listItem haben, können Sie diese Eigenschaften aus der Suche abrufen. Wenn Sie eine erweiterte Eigenschaft für eine Datei abrufen möchten, geben Sie den listItem-Typ in der Anforderung an.

Wenn die in der Anforderung angegebenen Felder weder im Schema vorhanden noch als abrufbar gekennzeichnet sind, werden sie in der Antwort nicht zurückgegeben. Ungültige Felder in der Anforderung werden automatisch ignoriert.

Wenn Sie in der Anforderung keine Felder angeben, erhalten Sie die Standardeigenschaften für alle Typen. Bei erweiterten Eigenschaften verhalten sich listItem und externalItem unterschiedlich, wenn in der Anforderung keine Felder übergeben werden:

  • listItem gibt kein benutzerdefiniertes Feld zurück.
  • externalItem gibt alle Felder zurück, die mit dem retrievable-Attribut im Microsoft Graph Connector-Schema für diese bestimmte Verbindung gekennzeichnet wurden.

Unterstützung für Keyword Query Language (KQL)

Geben Sie Textschlüsselwörter, Operatoren (z. B. AND, OR) und Eigenschaftseinschränkungen in der KQL-Syntax der tatsächlichen Suchabfragezeichenfolge an (query-Eigenschaft des query-Anforderungstextes). Die Syntax und der Befehl hängen von den Entitätstypen (in der entityTypes-Eigenschaft) ab, auf die Sie im selben query-Anforderungstext verweisen.

Je nach Entitätstyp variieren die durchsuchbaren Eigenschaften. Weitere Informationen finden Sie unter:

Sortieren von Suchergebnissen

Die Suchergebnisse in der Antwort werden in der folgenden Standardsortierreihenfolge sortiert:

  • message und event sind nach Datum sortiert.
  • Alle SharePoint-, OneDrive-, Personen- und Connectortypen sind nach Relevanz sortiert.

Mithilfe der query-Methode können Sie die Reihenfolge der Suche anpassen, indem Sie sortProperties für den requests-Parameter angeben. Hierbei handelt es sich um eine Sammlung von searchRequest-Objekten. Auf diese Weise können Sie eine Liste einer oder mehrerer sortierbarer Eigenschaften und die Sortierreihenfolge angeben.

Beachten Sie, dass Sortierergebnisse derzeit nur für die folgenden SharePoint- und OneDrive-Typen unterstützt werden: driveItem, listItem, list, site.

Die Eigenschaften, auf die die Sortierungsklausel angewendet wird, müssen im SharePoint-Suchschema sortiert werden. Wenn die in der Anforderung angegebene Eigenschaft nicht sortiert ist oder nicht vorhanden ist, gibt die Antwort einen Fehler, HTTP 400 Bad Request, zurück. Beachten Sie, dass es nicht möglich ist, Dokumente mithilfe von sortProperty nach Relevanz zu sortieren.

Wenn Sie den name eines sortProperty-Objekts angeben, können Sie entweder den Namen der Eigenschaft aus dem Microsoft Graph-Typ (z. B. in driveItem) oder den Namen der verwalteten Eigenschaft im Suchindex verwenden.

Unter Suchergebnisse sortieren finden Sie Beispiele, die zeigen, wie die Ergebnisse sortiert werden können.

Verfeinern von Ergebnissen mithilfe von Aggregationen

Aggregationen (in SharePoint auch als Einschränkung bekannt) sind eine sehr beliebte Methode zur Verbesserung des Sucherlebnisses. Zusätzlich zu den Ergebnissen liefern sie ein gewisses Maß an aggregierten Informationen über den übereinstimmenden Satz von Suchergebnissen. Sie können z.B. Informationen über die am häufigsten vertretenen Autoren der Dokumente, die der Anfrage entsprechen, oder über die am häufigsten vertretenen Dateitypen usw. bereitstellen.

Geben Sie in searchRequest die Aggregationen an, die zusätzlich zu den Suchergebnissen zurückgegeben werden sollen. Die Beschreibung jeder Aggregation wird in aggregationOption definiert, die die Eigenschaft, auf der die Aggregation berechnet werden soll, und die Anzahl der searchBucket angibt, die in der Antwort zurückgegeben werden soll.

Die Eigenschaften, für die die Aggregation angefordert wird, müssen im SharePoint-Suchschema verfeinert werden können. Wenn die angegebene Eigenschaft nicht eingeschränkt werden kann bzw. nicht vorhanden ist, wird die Antwort HTTP 400 Bad Request zurückgegeben.

Sobald die Antwort zurückgesendet wird, die die Sammlung von searchBucket-Objekten enthält, ist es möglich, die Suchanfrage auf nur die übereinstimmenden Elemente zu verfeinern, die in einem searchBucket enthalten sind. Dies wird erreicht, indem der Wert aggregationsFilterToken in der Eigenschaft aggregationFilters der nachfolgenden searchRequest zurückgegeben wird.

Zurzeit werden Aggregationen für jede einschränkbare Eigenschaft auf den folgenden SharePoint- und OneDrive-Typen unterstützt: driveItem, listItem, Liste, Website und auf Microsoft Graph-Connectors externalItem.

Beispiele, die zeigen, wie Sie die Aggregation verwenden, um Suchergebnisse zu verfeinern und einzugrenzen, finden Sie unter Einschränken der Suchergebnisse.

Rechtschreibkorrektur anfordern

Die Rechtschreibkorrektur ist eine beliebte Methode zur Behebung von Abweichungen zwischen Tippfehlern in einer Benutzerabfrage und den richtigen Wörtern in übereinstimmenden Inhalten. Wenn in der ursprünglichen Benutzerabfrage Tippfehler erkannt werden, können Sie das Suchergebnis für die ursprüngliche Benutzerabfrage oder die korrigierte alternative Abfrage erhalten. Sie können auch die Informationen zur Rechtschreibkorrektur für Tippfehler in der queryAlterationResponse-Eigenschaft von searchResponse erhalten.

Geben Sie im Anforderungsteil der Abfragemethode die queryAlterationOptions an, die auf die Abfrage zur Rechtschreibkorrektur angewendet werden sollen. Die Beschreibung der queryAlterationOptions ist im searchRequest festgelegt.

Beispiele über die Verwendung von Rechtschreibkorrekturen finden Sie unter Rechtschreibkorrektur anfordern.

Anzeige-Layout durchsuchen

Mit der Such-API können Sie Suchergebnisse aus Connectors rendern, indem Sie das Anzeige-Layout oder die Ergebnisvorlage verwenden, die vom IT-Administrator für jeden Connector konfiguriert wurde. Die Ergebnisvorlagen sind Adaptive Karten. Dabei handelt es sich um eine semantisch sinnvolle Kombination aus Layout und Daten.

Um die Ergebnisvorlage unter searchresponseabzurufen, müssen Sie die enableResultTemplate-Eigenschaft auf true festlegen, die im resultTemplateOptions im searchRequest definiert ist. Die Antwort ist Teil von resultTemplateId für jeden Suchtreffer, der einem der Anzeige-Layouts zugeordnet ist, die im resultTemplates-Wörterbuch enthalten sind.

Beispiele zum Rendern von Suchergebnissen finden Sie unter Verwenden des Suchanzeigelayouts.

Fehlerbehandlung

Die Such-API gibt Fehlerantworten wie durch die OData-Fehlerobjektdefinition festgelegt zurück, wobei es sich bei jeder um ein JSON-Objekt mit einem Code und einer Nachricht handelt.

Bekannte Einschränkungen

Für die Such-API gelten die folgenden Einschränkungen:

  • Die query-Methode ist definiert, eine Sammlung von einer oder mehreren searchRequest-Instanzen gleichzeitig zu übergeben. Der Dienst unterstützt zurzeit jedoch nur eine einzelne searchRequest.

  • Die SearchRequest-Ressource unterstützt das gleichzeitige Übergeben von mehreren Entitätstypen. Derzeit ist die einzige unterstützte Kombination für SharePoint- und OneDrive-entityTypes: driveItem, drive, site, list, listItem. Eine Kombination aus message, event, SharePoint- und OneDrive-Typen oder externalItem wird zurzeit nicht unterstützt.

  • Die Eigenschaft contentSource, die die zu verwendende Verbindung definiert, gilt nur, wenn entityType als externalItem angegeben wird.

  • Die Such-API unterstützt keine benutzerdefinierte Sortierreihenfolge für message, event oder externalItem.

  • Die Such-API unterstützt keine Aggregationen für message, event, site oder drive.

  • Anpassungen in der SharePoint-Suche, z. B. ein benutzerdefiniertes Suchschema oder Ergebnisquellen, können den Betrieb der Microsoft Search-API beeinträchtigen.

Siehe auch