Freigeben über

Verwendung der Microsoft Search-API zum Abfragen von Daten

  • Artikel

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

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.

Achtung

Bei Ressourcen, die in einer Microsoft Search API-Anfrage und -Antwort verwendet werden, wurden Eigenschaften umbenannt oder entfernt, oder sie sind veraltet. Hier finden Sie weitere Einzelheiten über das Ende der Unterstützung. Aktualisieren Sie Such-API-Abfragen in allen früheren Apps entsprechend.

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 in einer Suche nicht auf mehr Elemente zugreifen, als sie andernfalls aus einem entsprechenden GET-Vorgang mit den gleichen Berechtigungen und Zugriffssteuerungen abrufen 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
Suchen benutzerdefinierter Typen, die über Connectors importiert wurden contentSources
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 Ihrer Organisation.
bookmark Bookmark.Read.All Microsoft Search Lesezeichen in Microsoft Search in Ihrer Organisation.
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. Dokumentbibliotheken werden auch als Listen zurückgegeben.
listItem Sites.Read.All, Sites.ReadWrite.All SharePoint und OneDrive Elemente auflisten. Dateien und Ordner werden auch als Listenelemente zurückgegeben. listItem ist die Superklasse von driveItem.
externalItem ExternalItem.Read.All Microsoft Graph-Connectors Alle Inhalte, die mit der API für Microsoft Graph-Connectors aufgenommen wurden.
person People.Read Exchange Online Persönliche Kontakte und Kontakte oder adressierbare Objekte in Ihrer Organisation.
qna QnA.Read.All Microsoft Search Fragen und Antworten in Microsoft Search in Ihrer Organisation.
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 oder person, 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-Text ausgedrückt wird.

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 Entitäten listItem, driveItem und externalItem sind die einzigen unterstützten Entitäten, die das Abrufen erweiterter abrufbarer Felder ermöglichen, die im Schema konfiguriert sind. Sie können keine erweiterten Eigenschaften aus allen anderen Entitäten mithilfe der Such-API abrufen. Wenn Sie beispielsweise ein abrufbares Feld für externalItem im Suchschema erstellt haben oder eine abrufbare benutzerdefinierte Spalte für ein listItem- oder driveItem-Objekt vorhanden ist, können Sie diese Eigenschaften aus der Suche abrufen. Um eine erweiterte Eigenschaft für eine Datei abzurufen, geben Sie den listItem- oder driveItem-Typ in der Anforderung an.

Wenn die in der Anforderung angegebenen Felder entweder nicht im Schema vorhanden oder nicht 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, driveItem und externalItem unterschiedlich, wenn in der Anforderung keine Felder übergeben werden:

  • listItem gibt kein benutzerdefiniertes Feld zurück.
  • driveItem gibt ein internes listItem-Objekt mit einem leeren 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 Größenbeschränkungen, die zum Reduzieren von Ergebnissen in einem Antworttext verwendet werden. Die Verwendung von collapseProperties wirkt sich nur auf den Rückruf, aber nicht auf die Rangfolge/Sortierung aus.

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.

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

Die Eigenschaften, auf die die Collapse-Klausel angewendet wird, müssen abfragbar und entweder sortierbar oder verfeinernd sein. Beim Reduzieren mehrerer Ebenen sollte jede nachfolgende Eigenschaftsbegrenzungsgröße, die in einer Anforderung mit mehreren Ebenen angegeben ist, kleiner oder gleich dem vorherigen sein. Andernfalls gibt die Antwort einen HTTP 400 Bad Request Fehler zurück.

Beispiele, die zeigen, wie Ergebnisse reduziert werden, 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.

Das Sortieren von Ergebnissen wird derzeit nur für die folgenden SharePoint- und OneDrive-Typen unterstützt: driveItem, listItem, list, site.

Die Eigenschaften, auf die die Sortierklausel angewendet wird, müssen im SharePoint-Suchschema sortierbar sein. Wenn die in der Anforderung angegebene Eigenschaft nicht sortiert werden kann oder nicht vorhanden ist, gibt die Antwort den Fehler zurück. HTTP 400 Bad Request Sie können nicht angeben, dass Dokumente mithilfe von sortProperty nach Relevanz sortiert werden sollen.

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änkungen bezeichnet) sind eine beliebte Möglichkeit, eine Sucherfahrung zu verbessern. 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 oder nicht vorhanden ist, gibt die Antwort zurück HTTP 400 Bad Request.

Sobald die Antwort zurückgegeben wird, die die Auflistung von searchBucket-Objekten enthält, ist es möglich, die Suchanforderung nur auf 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.

Unter Einschränken der Suchergebnisse finden Sie Beispiele für die Verwendung von Aggregation zur Verfeinerung und Eingrenzung von Suchergebnissen.

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 searchRequest die queryAlterationOptions an, die auf die Abfrage für Rechtschreibkorrekturen angewendet werden soll. Details zur Eigenschaft queryAlterationOptions finden Sie unter searchAlterationOptions.

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 wahr in der enableResultTemplate-Eigenschaft festlegen, die im resultTemplateOptions im searchRequest definiert ist. Die Antwort enthält eine resultTemplateId für jeden Suchtreffer, der einem der Anzeige-Layouts zugeordnet ist, die im resultTemplates-Wörterbuch enthalten sind.

Beispiele finden Sie unter Verwenden von Anzeige-Layout durchsuchen.

Mit der Such-API können Gastbenutzer nach Elementen in SharePoint oder OneDrive suchen, die für sie freigegeben wurden. Um auf die Liste der Gastbenutzer zuzugreifen, wechseln Sie zum Microsoft 365 Admin Center, und wählen Sie im linken Navigationsbereich Benutzer und dann Gastbenutzer aus.

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.

Warnung zur Ende der Unterstützung von Schemaänderungen

Ab dem 31. August 2023 ist die Betaversion der externalItem-Ressource im Microsoft Graph-Namespace veraltet. Verwenden Sie in Zukunft die Version der Ressource im Microsoft.Graph.ExternalConnectors-Namespace . Stellen Sie sicher, dass Sie alle Namespaceabhängigkeiten vor dem angegebenen Datum aktualisieren. Alternativ können Sie den Übergang zur Version v1.0 der API in Betracht ziehen.

In der Betaversion wurden Eigenschaften, die in einer Suchanforderung und -Antwort verwendet werden, umbenannt oder entfernt. In den meisten Fällen werden die ursprünglichen Eigenschaften veraltet und durch die aktuellen Eigenschaften ersetzt, wie in der folgenden Tabelle aufgeführt.

Es wird empfohlen, vorhandene Apps so zu aktualisieren, dass sie die aktuellen Eigenschaften- und Typnamen verwenden und aktuelle Eigenschaftennamen in der Antwort abrufen. Aus Gründen der Abwärtskompatibilität sind die ursprünglichen Eigenschaften und Typen bis zum 30. September 2023 verfügbar und funktionieren. Danach werden sie entfernt.

Ressource Änderungstyp Original-Eigenschaft Aktuelle Eigenschaft
searchRequest Eigenschaft umbenennen stored_fields fields
searchQuery Eigenschaft umbenennen query_string queryString
searchQueryString Ressource wird nicht mehr unterstützt Nicht zutreffend Nicht zutreffend
searchHit Eigenschaft umbenennen _id hitId
searchHit Eigenschaft umbenennen _score rank
searchHit Eigenschaft entfernen _sortField Nicht zutreffend
searchHit Eigenschaft umbenennen _source resource
searchHit Eigenschaft umbenennen _summary summary
entityTypes Enumerationswert umbenennen unknownfuturevalue unknownFutureValue

Verwandte Inhalte