Personen auflistenList people

Namespace: Microsoft. GraphNamespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

Dient zum Abrufen einer Liste von Person -Objekten, die nach ihrer Relevanz für den Benutzersortiert sind, die durch die Kommunikations-und Zusammenarbeits Muster des Benutzers sowie Geschäftsbeziehungen bestimmt wird.Retrieve a list of person objects ordered by their relevance to the user, which is determined by the user's communication and collaboration patterns, and business relationships.

BerechtigungenPermissions

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) People.ReadPeople.Read
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) People.ReadPeople.Read
AnwendungApplication Nicht unterstütztNot supported.

HTTP-AnforderungHTTP request

GET /me/people
GET /users/{id | userPrincipalName}/people

Optionale AbfrageparameterOptional query parameters

Diese Methode unterstützt die folgenden OData-Abfrageparameter, mit denen die Antwort angepasst werden kann.This method supports the following OData query parameters to help customize the response.

NameName WertValue BeschreibungDescription
$filter$filter stringstring Dient zum Einschränken der Antwort auf diejenigen Personen, deren Datensätze die angegebenen Kriterien enthalten.Limits the response to only those people whose record contains the specified criteria.
$orderby$orderby Zeichenfolgestring Standardmäßig werden die Personen in der Antwort nach ihrer Relevanz für die Abfrage sortiert.By default the people in the response are sorted by their relevance to your query. Sie können die Reihenfolge der Personen in der Antwort mit dem $orderby-Parameter ändern.You can change the order of the people in the response using the $orderby parameter.
$search$search Zeichenfolgestring Dient für die Suche nach Personen anhand des Namens oder des Alias.Search for people by name or alias. Unterstützt Fuzzyübereinstimmung.Supports Fuzzy matching. Parameter funktioniert nur für die Suche nach den relevanten Personen des angemeldeten Benutzers, nicht für die Suche nach Personen, die für andere Benutzer relevant sind.Parameter only works for searching the signed-in user's relevant people, not for searching people relevant to other users. Unterstützt auch das Schlüsselwort topic, um Personen anhand von Themen zu finden, die aus E-Mail-Gesprächen mit dieser Person extrahiert wurden.Also supports the topic keyword to find people based on topics extracted from e-mail conversations with that person. Sehen Sie sich den Abschnitt Eine Fuzzy-Suche durchführen unter Relevante Informationen über Personen erhalten für Informationen und Beispiele an.See the Perform a fuzzy search section at Get relevant information about people for information and examples.
$select$select stringstring Durch Trennzeichen getrennte Liste der Eigenschaften, die in die Antwort eingeschlossen werden sollen. Wählen Sie für optimale Leistung nur eine Teilmenge der benötigten Eigenschaften.Comma-separated list of properties to include in the response. For optimal performance, only select the subset of properties needed.
$skip$skip intint Die ersten n Ergebnisse werden übersprungen. Hilfreich für Paging. Wird bei Verwendung von $search nicht unterstützt.Skip the first n results, useful for paging. This is not supported when using $search.
$top$top intint Anzahl der Ergebnisse, die zurückgegeben werden.Number of results to be returned.

AnforderungsheaderRequest headers

NameName BeschreibungDescription
AuthorizationAuthorization Bearer {token}. Erforderlich.Bearer {token}. Required.
AnnehmenAccept application/jsonapplication/json

AnforderungstextRequest body

Geben Sie für diese Methode keinen Anforderungstext an.Do not supply a request body for this method.

AntwortResponse

Wenn die Methode erfolgreich verläuft, 200 OK werden der Antwortcode und eine Auflistung von Person -Objekten im Antworttext zurückgegeben.If successful, this method returns a 200 OK response code and a collection of person objects in the response body.

BeispieleExamples

DurchsuchenBrowse

Die Anforderungen in diesem Abschnitt erhalten die Personen, die für den angemeldeten Benutzer am/merelevantesten sind (), basierend auf Kommunikation, Zusammenarbeit und Geschäftsbeziehungen.The requests in this section get the people most relevant to the signed-in user (/me), based on communication, collaboration, and business relationships.

Standardmäßig gibt jede Antwort 10 Datensätze zurück, aber Sie können dies mit dem Parameter $top ändern.By default, each response returns 10 records, but you can change this using the $top parameter. Für diese Anforderungen ist die Berechtigung People. Read erforderlich.These requests require the People.Read permission.

AnforderungRequest

Es folgt ein Beispiel für die Standardanforderung.The following is an example of the default request.

GET https://graph.microsoft.com/beta/me/people

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

Anfordern einer nachfolgenden PersonenseiteRequesting a subsequent page of people

Wenn die erste Antwort nicht die vollständige Liste der relevanten Personen enthält, können Sie mit $top und $skip eine zweite Anforderung für das Abrufen weiterer Seiten mit Informationen einreichen. Wenn die vorherige Anforderung zusätzliche Informationen enthält, ruft die darauf folgende Anforderung die nächste Seite der Personen vom Server ab.If the first response does not contain the complete list of relevant people, you can make a second request using $top and $skip to request additional pages of information. If the previous request has additional information, the following request gets the next page of people from the server.

GET https://graph.microsoft.com/beta/me/people/?$top=10&$skip=10

Sortieren der AntwortSort the response

Standardmäßig werden die Personen in der Antwort nach ihrer Relevanz für die Abfrage sortiert.By default the people in the response are sorted by their relevance to your query. Sie können die Reihenfolge der Personen in der Antwort mit dem $orderby-Parameter ändern.You can change the order of the people in the response using the $orderby parameter. Diese Abfrage wählt die für Sie relevantesten Personen aus, sortiert sie nach ihrem Anzeigenamen und gibt dann die ersten 10 Personen auf der sortierten Liste zurück.This query selects the people most relevant to you, sorts them by their display name, and then returns the first 10 people on the sorted list.

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

Ändern der Anzahl der zurückgegebenen Personen und der zurückgegebenen FelderChanging the number of people returned and the fields returned

Sie können die Anzahl der Personen ändern, die in der Antwort zurückgegeben wird, indem Sie den $top-Parameter festlegen.You can change the number of people returned in the response by setting the $top parameter.

Im folgenden Beispiel werden die 1.000 Personen angefordert, /medie am relevantesten sind.The following example requests the 1,000 people most relevant to /me. Die Anforderung beschränkt auch die Menge der Daten, die vom Server zurückgesendet werden, indem nur der Anzeigename der Person angefordert wird.The request also limits the amount of data sent back from the server by requesting only the display name of the person.

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

Auswahl der zurückzugebenden FelderSelecting the fields to return

Sie können die vom Server zurückgegebene Datenmenge einschränken, indem Sie mithilfe des Parameters $Select ein oder mehrere Felder auswählen.You can limit the amount of data returned from the server by using the $select parameter to choose one or more fields. Das Feld *@odata.id* wird immer zurückgegeben.The *@odata.id* field is always returned.

Im folgenden Beispiel wird die Antwort auf den DisplayName und die e- der 10 relevantesten Personen beschränkt.The following example limits the response to the DisplayName and EmailAddress of the 10 most relevant people.

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

Verwendung eines Filters zur Begrenzung der AntwortUsing a filter to limit the response

Sie können den $filter-Parameter zum Einschränken der Antwort auf diejenigen Personen einschränken, deren Datensätze die angegebenen Kriterien enthalten.You can use the $filter parameter to limit the response to only those people whose record contains the specified criteria.

Die folgende Abfrage schränkt die Antwort auf Personen mit der Quelle "Directory" ein.The following query limits the response to people with the source "Directory."

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

Auswählen der Felder, die in einer gefilterten Antwort zurückgegeben werden sollenSelecting the fields to return in a filtered response

Sie können die $select- und $filter-Parameter gemeinsam verwenden, um eine benutzerdefinierte Liste der für den Benutzer relevanten Personen zu erstellen und nur die Felder abzurufen, die Ihre Anwendung benötigt.You can combine the $select and $filter parameters to create a custom list of people relevant to the user and get only the fields that your application needs.

Im folgenden Beispiel werden der Name und die e-mailnamendatei von Personen abgerufen, deren Anzeigename dem angegebenen Namen entspricht.The following example gets the DisplayName and EmailAddress of people whose display name equals the specified name. In diesem Beispiel werden nur Personen zurückgegeben, deren Anzeigename "Nestor Kellum" ist.In this example, only people whose display name equals "Nestor Kellum" are returned.

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

Durchsuchen von PersonenSearch people

Die Anforderungen in diesem Abschnitt erhalten auch die Personen, die für den angemeldeten Benutzer am/merelevantesten sind ().The requests in this section also get the people most relevant to the signed-in user (/me). Für Suchanforderungen ist die Berechtigung People. Read erforderlich.Search requests require the People.Read permission.

Verwenden der Suche zum Auswählen von PersonenUsing search to select people

Verwenden Sie den $search-Parameter zum Auswählen von Personen, die bestimmte Kriterien erfüllen.Use the $search parameter to select people who meet a particular set of criteria.

Die folgende Suchabfrage gibt Personen zurück, /me die relevant sind, deren Name oder Nachname mit dem Buchstaben "j" beginnt.The following search query returns people relevant to /me whose GivenName or Surname begins with the letter "j".

GET https://graph.microsoft.com/beta/me/people/?$search=j

Mit der Suche ein relevantes Thema angebenUsing search to specify a relevant topic

Die folgende Anforderung gibt Personen zurück, /me deren Name "Ma" enthält und die eine Assoziation mit "Feature Planning" aufweisen.The following request returns people relevant to /me whose name contains "ma" and who have an association with "feature planning."

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

Die folgende Anforderung führt eine Suche nach einer Person namens "Hermaini Hall" aus.The following request does a search for a person named "Hermaini Hall." Da eine Person mit dem Namen "Herminia Hull" für den angemeldeten Benutzer relevant ist, werden die Informationen für "Herminia Hull" zurückgegeben.Because there is a person named "Herminia Hull" relevant to the signed-in user, the information for "Herminia Hull" is returned.

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

Die folgende Anforderung Ruft die Personen auf, die am relevantesten für eine andere Person in der Organisation des Benutzers sind.The following request gets the people most relevant to another person in the user's organization. Für diese Anforderung ist die Berechtigung User. ReadBasic. all für People. Read. All erforderlich.This request requires the User.ReadBasic.All for People.Read.All permission. In diesem Beispiel werden die relevanten Personen von Nestor Kellum angezeigt.In this example, Nestor Kellum's relevant people are displayed.

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/