Verwendung der Microsoft Search-API zum Abfragen von Daten

  • Artikel

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 gängigen Anwendungsfälle der Abfragemethode basierend auf den Eigenschaften und Parametern aufgeführt, die Sie im SearchRequest-Text der Abfrage festlegen.

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 reduzieren collapseProperties
Suchergebnisse sortieren sortProperties
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
Akronym Acronym.Read.All Microsoft Search Akronyme in Microsoft Search in Ihrem organization.
bookmark Bookmark.Read.All Microsoft Search Lesezeichen in Microsoft Search in Ihrem organization.
chatMessage Chat.Read, Chat.ReadWrite, ChannelMessage.Read.All Teams Teams-Nachrichten.
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.
qna QnA.Read.All Microsoft Search Fragen und Antworten in Microsoft Search in Ihrem organization.
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.

Die Obergrenze für SharePoint- oder OneDrive-Elemente beträgt 1000. 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 den Standardeigenschaftensatz 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). Der XRANK-Operator erhöht die dynamische Rangfolge von Elementen basierend auf bestimmten Begriffsereignissen innerhalb des Übereinstimmungsausdrucks, ohne zu ändern, welche Elemente mit der Abfrage übereinstimmen. 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:

Suchergebnisse reduzieren

Die collapseProperties-Eigenschaft enthält eine Reihe von Kriterien, Feldern und Begrenzungsgrößen, die zum Reduzieren von Ergebnissen in einem Antworttext verwendet werden. Die Verwendung von collapseProperties wirkt sich nur auf die Abrufaktionen aus, aber nicht auf die Rangfolge/Sortierung.

Mit der Abfragemethode können Sie die collapse-Eigenschaft anpassen, indem Sie collapseProperties für den Parameter angeben, der requests eine Auflistung von collapseProperty-Objekten ist. Auf diese Weise können Sie eine Gruppe von einer oder mehreren Reduzieren-Eigenschaften angeben.

Beachten Sie, dass das Reduzieren von Ergebnissen derzeit für die folgenden Entitätstypen unterstützt wird: driveItem, listItem, drive, list, site, externalItem.

Damit die Collapse-Klausel effektiv verwendet werden kann, müssen die Eigenschaften, auf die Sie sie anwenden, abfragbar und entweder sortierbar oder verfeinernd sein. Bei Verwendung von Multi-Level-Collapse ist es wichtig zu beachten, dass die in einer Anforderung mit mehreren Ebenen angegebene Begrenzungsgröße jeder nachfolgenden Eigenschaft gleich oder kleiner als die vorherige sein sollte. Wenn die Limitgröße einer nachfolgenden Eigenschaft den vorherigen überschreitet, antwortet der Server mit einem HTTP 400 Bad Request Fehler.

Weitere Beispiele zum Reduzieren von Ergebnissen finden Sie unter Reduzieren von Suchergebnissen .

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.

Mit der Abfragemethode können Sie die Suchreihenfolge anpassen, indem Sie sortProperties für den requests Parameter angeben, der eine Auflistung von sortProperty-Objekten ist. 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 AggregationsFilterToken-Wert in der aggregationFilters-Eigenschaft 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. In der folgenden Tabelle sind die unterstützten Kombinationen aufgeführt.

    Entitätstyp acronym bookmark message ChatMessage Laufwerk driveItem event externalItem Liste listItem Person qna Website
    acronym True True - - - - - - - - - True -
    bookmark True True - - - - - - - - - True -
    ChatMessage - - - Wahr - - - - - - - - -
    Laufwerk - - - - True True - True True True - - True
    driveItem - - - - True True - True True True - - True
    event - - - - - - Wahr - - - - - -
    externalItem - - - - True True - True True True - - True
    Liste - - - - True True - True True True - - True
    listItem - - - - True True - True True True - - True
    message - - Wahr - - - - - - - - - -
    Person - - - - - - - - - - Wahr - -
    qna True True - - - - - - - - - True -
    Website - - - - True True - True True True - - True

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

  • Die Such-API unterstützt keine benutzerdefinierte Sortierung für akronym, bookmark, message, chatMessage, event, person, qna oder externalItem.

  • Die Such-API unterstützt keine Aggregationen für Akronym, Lesezeichen, Nachricht, Ereignis, Website, Person, qna oder Laufwerk.

  • Die Such-API unterstützt xrank nicht für akronym, bookmark, message, chatMessage, event, person, qna oder externalItem.

  • Die Gastsuche unterstützt keine Suche nach akronym, bookmark, message, chatMessage, event, person, qna oder externalItem.

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

  • Die Such-API unterstützt das Suchschema auf Websiteebene nicht. Verwenden Sie das Suchschema auf Mandantenebene oder das Standardschema.

Verwandte Inhalte