Verwenden der Microsoft Search-API zum Suchen von Personen

Artikel
04/17/2024

Microsoft Graph-Anwendungen können die Microsoft Search-API verwenden, um die Personen abzurufen, die für einen Benutzer am relevantesten sind. Relevanz wird durch die Kommunikations- und Zusammenarbeitsmuster und Geschäftsbeziehungen des Benutzers bestimmt. Personen können lokale Kontakte oder aus dem Verzeichnis eines organization oder Personen aus der letzten Kommunikation sein.

Neben der Generierung dieser Erkenntnis bietet die Suche auch Unterstützung für Fuzzyabgleich und die Möglichkeit, die Liste der Benutzer abzurufen, die für einen anderen Benutzer im organization des angemeldeten Benutzers relevant sind.

Personen-APIs

Sie können die folgenden APIs verwenden, um innerhalb eines organization nach Personen zu suchen.

/Suche
/Menschen

Hinweis

Es wird empfohlen, dass Benutzer den /search Endpunkt anstelle des /people Endpunkts aufrufen. In Zukunft werden alle zukünftigen Investitionen nur im /search Endpunkt verfügbar sein. Der /people Endpunkt befindet sich im Wartungsmodus.

Zurückgegebene Personeneigenschaften

Die Personen-API gibt den folgenden Satz von Eigenschaften zurück.

Eigenschaft	Typ
additionalOfficeLocation	String
CompanyName	String
department	String
displayName	String
emailAddress	String
givenName	String
hitId	String
imAddress	String
jobTitle	String
officeLocation	String
personType	String
phones	String
rank	Ganze Zahl
Zusammenfassung	String
surname	String
userPrincipalName	String

Personentypen

Die folgende Tabelle zeigt Personentypen und Untertypen, die in der Personen-API unterstützt werden.

Unterstützte Personen, Gruppen und Räume – Variationen	Details zum Empfängertyp	Postfach	Verzeichnis	Personen Typ	Personen Untertyp	Anmerkungen
Organisationsbenutzer	UserMailbox, MailUser	v	v	Person	OrganizationUser	Ein Benutzer, der zum organization gehört.
Organisationsbenutzer ohne E-Mail-Adresse	Benutzer	Y (standardmäßig deaktiviert)	Y (standardmäßig deaktiviert)	Person	OrganizationUser	Ein Benutzer, der zum organization gehört.
Organisationskontakt	MailContact, Kontakt	N	J	Person	OrganisationKontakt	Ein Kontakt, der der globalen Adressliste (GAL) vom Mandantenadministrator explizit hinzugefügt wurde, der aber nicht Teil der organization ist.
Privater Kontakt	Kontakt	J	Nicht zutreffend	Person	PersonalContact	Ein Kontakt, der explizit vom Benutzer erstellt wurde und nicht zum organization gehört. Wenn der Benutzer manuell zu seinen Kontakten einen Teil des organization hinzufügt, wird er weiterhin als `OrganizationUser`klassifiziert.
Privater Kontakt ohne E-Mail-Adresse	Kontakt	Y (standardmäßig deaktiviert)	Nicht zutreffend	Person	PersonalContact	Ein Kontakt, der explizit vom Benutzer erstellt wurde und nicht zum organization gehört. Wenn der Benutzer manuell zu seinen Kontakten einen Teil des organization hinzufügt, wird er weiterhin als `OrganizationUser`klassifiziert.
Impliziter Kontakt aus dem Kommunikationsverlauf	Kontakt	J	Nicht zutreffend	Person	ImplicitContact	Ein Kontakt, der aus dem Kommunikationsverlauf (E-Mail und Chat) abgeleitet wurde, über den wir nicht genügend Informationen haben, um festzustellen, ob es sich um eine Person, Gruppe usw. handelt. Bei Geschäftskonten ist dies immer ein externer organization Kontakt, da innerhalb organization Kontakte, die im Kommunikationsverlauf gefunden werden, immer als `OrganizationUser`klassifiziert werden. Bei Consumerkonten wird alles, was kein `PersonalContact` ist, als `ImplicitContact`klassifiziert.
Impliziter Kontakt aus dem Chatverlauf	Kontakt	J	Nicht zutreffend	Person	ChatImplicitContact	Identisch mit `ImplicitContact`, aber wenn der Kommunikationsverlauf ausschließlich aus dem Chat stammt.
Raum	Räume	v	v	Andere	Raum
Gast	GuestUser	v	v	Andere	Gast
Ausgeblendeter Gast	GuestUser	Y (standardmäßig deaktiviert)	Y (standardmäßig deaktiviert)	Andere	Gast
Moderne Gruppe	Gruppe	v	v	Gruppe	UnifiedGroup	Gruppe bekannt als: Exchange 365-Gruppe, moderne Gruppen, Microsoft 365-Gruppen. Weitere Informationen zu Microsoft 365-Gruppen finden Sie unter Informationen zu Microsoft 365-Gruppen.
Teams-Gruppe	Gruppe	v	v	Gruppe	UnifiedGroup	Identisch mit Microsoft 365-Gruppen, stellt aber intern ein Team in Microsoft Teams dar.
Ausgeblendete Teams-Gruppe	Gruppe	Y (standardmäßig deaktiviert)	J	Gruppe	UnifiedGroup	Ausgeblendete Teams-Gruppe.
Verteilerliste	Gruppe	v	v	Gruppe	PublicDistributionList	Klassische Exchange-Verteilerliste oder E-Mail-aktivierte Sicherheitsgruppe.
Persönliche Verteilerliste	Kontakt	Y (standardmäßig deaktiviert)	Nicht zutreffend	Gruppe	PersonalDistributionList	Eine virtuelle Verteilergruppe, die vom Benutzer als Helfer erstellt wird, um auf einfache Weise E-Mails an mehrere Kontakte zu senden. Wird nur für Outlook im Web Verfassen als UX-Feature verwendet, nicht für andere Aufrufer zurückgegeben.
Ausgeblendetes Objekt eines beliebigen Typs außer Gast- und Teams-Gruppe		N	N

Anfragedetails

Machen Sie die Ergebnisse der Personen-API genauer, indem Sie zusätzliche Details angeben, wenn Sie eine Anforderung stellen. Im Folgenden finden Sie einige Möglichkeiten, die Anforderungen genauer zu gestalten.

Beispiel 1: Nur Postfachergebnisse

"Provenances": ["Mailbox"]

Beispiel 2: Ergebnisse aus beiden Quellen

"Provenances": ["Mailbox", "Directory"]

Ergebnisquelle

Personen Ergebnisse stammen aus zwei Quellen: Postfach oder Verzeichnis. Standardmäßig stammen die Ergebnisse aus beiden Quellen, wobei Konflikte entfernt werden, wodurch sichergestellt wird, dass keine gleichen Werte zurückgegeben werden.

Hinweis: Im Falle eines Konflikts werden Verzeichnisquellen bevorzugt.

Postfachergebnisse bestehen aus:

Personen, der Ihnen eine E-Mail gesendet hat
Personen, an wen Sie eine E-Mail gesendet haben
Personen, mit der Sie sich getroffen haben
Personen, mit denen Teams chatten
Personen im Organigramm Ihres Vorgesetzten
Öffentliche Kontakte der oben genannten Personen

Relevante Aspekte für den Anwendungsfall, wenn eine Verzeichnisquelle in der globalen Adressierungsliste in Microsoft Entra ID durchsucht:

Gilt nicht für Verbraucherbenutzer
Personen, die sich nicht in der globalen Adressierungsliste des Aufrufers befinden, werden nicht zurückgegeben.
Personen, die von IBP (Information Barrier Protocol) ausgeblendet werden, werden nicht zurückgegeben.
Personen, die in der Adressliste ausgeblendet sind, werden nicht zurückgegeben.

Abrufen weiterer Ergebnisse

Geben Sie die Größe an, um weitere Ergebnisse zu erhalten. Standardmäßig werden maximal 25 Ergebnisse basierend auf den Übereinstimmungen der Suchabfrage zurückgegeben.

"Size": 25

Angeben des Mindestindexes für paging

Legen Sie den Mindestindex für paging fest, um die erste Ergebnisseite anzugeben. Standardmäßig ist 0 der Mindestindex für paging, und das erste Ergebnis ist das relevanteste.

"From": 0

Auswählen der zurückgegebenen Felder

Die API gibt einen Satz von Standardeigenschaften zurück, aber Sie können eine Anforderung anpassen, um eine bestimmte Anzahl von Eigenschaften zurückzugeben. Im folgenden Beispiel wird die Antwort auf die Eigenschaften DisplayName, EmailAddresses und phones beschränkt.

"Fields": ["DisplayName", "EmailAddresses", "phones"]

Verwenden eines Filters zum Einschränken der Antwort

Verwenden Sie das Filter-Objekt , um die Antwort auf bestimmte Werte zu beschränken. Mögliche Filterwerte sind: PeopleType, PeopleSubType.

Die folgenden Beispiele zeigen Anforderungen, die das Filter-Objekt verwenden, um Personen zurückzugeben, deren Datensatz die angegebenen Kriterien enthält.

Beispiel 1: Filtern nach Personenvorschlägen

Im folgenden Beispiel wird die Antwort nur auf Personenvorschläge beschränkt. Die Antwort enthält sowohl private als auch organization Kontakte.

"Filter": {
  "And": [
    {
      "Term": {
        "PeopleType": "Person"
      }
    }
  ]
},

Beispiel 2: Filtern nach Personenvorschlägen innerhalb des organization

Im folgenden Beispiel wird das Reponse nur auf Geschäftsbenutzer beschränkt.

"Filter": {
  "And": [
    {
      "Term": {
        "PeopleType": "Person"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    }
  ]
},

Beispiel 3: Filtern nach allen Benutzern, Verteilerlisten oder modernen Verteilerlisten im organization

Im folgenden Beispiel wird die Antwort auf verschiedene Kategorien von PeopleSubtype beschränkt.

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "PublicDistributionList"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "UnifiedGroup"
      }
    }
  ]
},

Beispiel 4: Filtern nach organization Benutzern und Besprechungsräumen

Im folgenden Beispiel wird die Antwort auf organization Benutzer und Besprechungsräume beschränkt.

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "Rooms"
      }
    }
  ]
},

Beispiel 5: Filtern nach organization Benutzern und Gästen

Im folgenden Beispiel wird die Antwort auf organization Benutzer und Gäste beschränkt.

"Filter": {
  "Or": [
    {
      "Term": {
        "PeopleSubtype": "OrganizationUser"
      }
    },
    {
      "Term": {
        "PeopleSubtype": "Guest"
      }
    }
  ]
},

Beispiel 6: Kombinieren mehrerer Filter

Im folgenden Beispiel werden mehrere Filter kombiniert, um die Antwort auf die angegebenen Kriterien zu beschränken.

"Filter": {
  "And": [
    {
      "Or": [
        {
          "Term": {
            "PeopleType": "Person"
          }
        },
        {
          "Term": {
            "PeopleType": "Other"
          }
        }
      ]
    },
    {
      "Or": [
        {
          "Term": {
            "PeopleSubtype": "OrganizationUser"
          }
        },
        {
          "Term": {
            "PeopleSubtype": "Guest"
          }
        }
      ]
    }
  ]
},

Vollständige Anforderung

Beispiel: Search Person anhand des Namens

Die folgende Anforderung ruft die Personen ab, die für den angemeldeten Benutzer am relevantesten sind, basierend auf Kommunikations- und Zusammenarbeitsmustern und Geschäftsbeziehungen.

Anforderung

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
  "requests": [
    {
      "entityTypes": [
        "person"
      ],
      "query": {
        "queryString": "contoso"
      },
      "from": 0,
      "size": 25
    }
  ]
}

Antwort

Im Folgenden finden Sie ein Beispiel für die Antwort, die eine Nachricht enthält, die dem Suchkriterium entspricht.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.searchResponse",
    "value": [
        {
            "hitsContainers": [
                {
                    "total": 1,
                    "moreResultsAvailable": false,
                    "hits": [
                        {
                            "hitId": "fc138b85-18ac-48e0-80a4-633ae4b594e0@41f988bf-86f1-53af-91ab-2d7cd034db47",
                            "rank": 1,
                            "summary": "",
                            "resource": {
                                "@odata.type": "#microsoft.graph.person",
                                "displayName": "Example User",
                                "givenName": "User",
                                "surname": "User",
                                "department": "Finance",
                                "officeLocation": "London",
                                "userPrincipalName": "example.user@contoso.com",
                                "emailAddresses": [
                                    {
                                        "address": "example.user@contoso.com",
                                        "rank": 1
                                    }
                                ],
                                "phones": [
                                    {
                                        "type": "business",
                                        "number": "+44 (20) 12345678"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Nächste Schritte

Verwendung der Microsoft Search-API zum Abfragen von Daten