Verwenden der People API in Microsoft Graph zum Abrufen von Informationen über relevante PersonenUse the People API in Microsoft Graph to get information about the people most relevant to you

Microsoft Graph-Anwendungen können die People API zum Abrufen von Personen verwenden, 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, Kontakte aus sozialen Netzwerken, aus dem Verzeichnis Ihrer Organisation und Personen aus kürzlichen Unterhaltungen (z. B. E-Mail und Skype) sein. Neben Generierung dieser Einblicke bietet die People API auch Unterstützung für Fuzzyübereinstimmungen bei Suchvorgängen sowie die Möglichkeit, eine Liste der für einen Benutzer relevanten Benutzer in der Organisation des angemeldeten Benutzers abzurufen. Die People API ist insbesondere beim Auswählen von Personen hilfreich, z. B. beim Verfassen einer E-Mail oder beim Erstellen einer Besprechung. Sie können die People API beispielsweise beim Verfassen von E-Mails verwenden.Microsoft Graph applications can use the People API to retrieve the people who are most relevant to a user. Relevance is determined by the user’s communication and collaboration patterns and business relationships. People can be local contacts, contacts from social networking or from an organization’s directory, and people from recent communications (such as email and Skype). Along with generating this insight, the People API also provides fuzzy matching search support and the ability to retrieve the list of users relevant to another user in the signed-in user's organization. The People API is particularly useful for people picking scenarios, such as composing an email or creating a meeting. For example, you can use the People API in email compose scenarios.

AuthorizationAuthorization

Zum Aufrufen der People API in Microsoft Graph benötigt Ihre App die entsprechenden Berechtigungen:To call the People API in Microsoft Graph, your app will need the appropriate permissions:

  • People.Read – Verwenden Sie diese Berechtigung für allgemeine People API-Aufrufe, beispielsweise https://graph.microsoft.com/v1.0/me/people/. People.Read erfordert die Zustimmung des Endbenutzers.People.Read - Use to make general People API calls; for example, https://graph.microsoft.com/v1.0/me/people/. People.Read requires end user consent.
  • People.Read.All – Erforderlich, um die für einen bestimmten Benutzer relevanten Personen in den Aufrufen der Organisation des angemeldeten Benutzers (https://graph.microsoft.com/v1.0/users/{id}/people) abzurufen.People.Read.All - Required to retrieve the people most relevant to a specified user in the signed-in user’s organization (https://graph.microsoft.com/v1.0/users/{id}/people) calls. People.Read.All erfordert die Zustimmung des Administrators.People.Read.All requires admin consent.

Durchsuchen von PersonenBrowse people

Bei den Anforderungen in diesem Abschnitt werden die für den angemeldeten Benutzer oder einen bestimmten Benutzer, der bei der Organisation des Benutzers angemeldet ist, relevantesten Personen abgerufen (/me). Für diese Anforderungen ist die Berechtigung „People.Read“ oder „People.Read.All“ erforderlich. Standardmäßig gibt jede Antwort 10 Datensätze zurück, Sie können diese Einstellung jedoch mithilfe des $top-Abfrageparameters ändern.The requests in this section get the people most relevant to the signed-in user (/me), or to a specific user in the signed-in user’s organization. These requests require the People.Read or People.Read.All permission respectively. By default, each response returns 10 records, but you can change this by using the $top query parameter.

Abrufen einer Sammlung relevanter PersonenGet a collection of relevant people

Mit der folgenden Anforderung werden die für den angemeldeten Benutzer relevantesten Personen (/me) auf Grundlage von Kommunikations- und Zusammenarbeitsmustern sowie Geschäftsbeziehungen abgerufen.The following request gets the people most relevant to the signed-in user (/me), based on communication and collaboration patterns and business relationships.

GET https://graph.microsoft.com/v1.0/me/people/

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mithilfe des $top-Abfrageparameters ändern. In diesem Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this by using the $top query parameter. This example uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.onmicrosoft.com",
      "imAddress": "sip:LorrieF@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.onmicrosoft.com",
      "imAddress": "sip:MaynardD@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.onmicrosoft.com",
      "imAddress": "sip:DarrelH@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Anfordern einer nachfolgenden Seite mit PersonenRequest 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/v1.0/me/people/?$top=3&$skip=10

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mithilfe des $top-Abfrageparameters ändern. In diesem Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this by using the $top query parameter. This example uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola",
      "givenName": "Felix",
      "surname": "Coppola",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Legal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2109",
      "profession": "",
      "userPrincipalName": "FelixC@contoso.onmicrosoft.com",
      "imAddress": "sip:FelixC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0104"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland",
      "givenName": "Lenora",
      "surname": "Rowland",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/1106",
      "profession": "",
      "userPrincipalName": "LenoraR@contoso.onmicrosoft.com",
      "imAddress": "sip:LenoraR@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 954 555 0118"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette",
      "givenName": "Manuel",
      "surname": "Collette",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Accountant II",
      "companyName": null,
      "yomiCompany": "",
      "department": "Finance",
      "officeLocation": "98/2202",
      "profession": "",
      "userPrincipalName": "ManuelC@contoso.onmicrosoft.com",
      "imAddress": "sip:ManuelC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Sortieren der AntwortSort the response

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

GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mit dem $top-Parameter ändern. Im folgenden Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this by using the $top parameter. The following example uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos",
      "givenName": "Adriana",
      "surname": "Ramos",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/2111",
      "profession": "",
      "userPrincipalName": "AdrianaR@contoso.onmicrosoft.com",
      "imAddress": "sip:AdrianaR@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 425 555 0109"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley",
      "givenName": "Alyce",
      "surname": "Cooley",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "131/1104",
      "profession": "",
      "userPrincipalName": "AlyceC@contoso.onmicrosoft.com",
      "imAddress": "sip:AlyceC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 858 555 0110"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke",
      "givenName": "Alyssa",
      "surname": "Clarke",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Corporate Security Officer",
      "companyName": null,
      "yomiCompany": "",
      "department": "Operations",
      "officeLocation": "24/1106",
      "profession": "",
      "userPrincipalName": "AlyssaC@contoso.onmicrosoft.com",
      "imAddress": "sip:AlyssaC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 262 555 0106"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Ändern der Anzahl von Personen und der zurückgegebenen FelderChange the number of people and 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 folgende Beispiel werden die für /me 1.000 relevantesten Personen angefordert. Die Anforderung begrenzt außerdem die Menge der Daten, die vom Server gesendet werden, indem nur der displayName der Person angefordert wird.The following example requests the 1,000 people most relevant to /me. The request also limits the amount of data sent back from the server by requesting only the displayName of the person.

GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName

Das folgende Beispiel zeigt die Antwort.The following example shows the response.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye"
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman"
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey"
    },
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Roscoe Seidel"
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke"
    },
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos"
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley"
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Wayne Leeper"
    },
    {
      "id": "E7D40AC5-0078-4575-B1F3-F738124C4BC9",
      "displayName": "Jan Travis"
    },
    {
      "id": "6F99D1CC-4FCC-49E4-9160-E8AB01BF3E83",
      "displayName": "Charlotte Delacruz"
    },
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola"
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland"
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette"
    }
  ]
}

Auswählen der zurückgegebenen FelderSelect the fields to return

Sie können die Menge der vom Server zurückgegebenen Daten einschränken, indem Sie den $select-Parameter zum Auswählen der Felder verwenden. Das @odata.id-Feld wird immer zurückgegeben.You can limit the amount of data returned from the server by using the $select parameter to choose one or more fields. The @odata.id field is always returned.

Im folgenden Beispiel wird die Antwort auf displayName und scoredEmailAddresses der 10 relevantesten Personen begrenzt.The following example limits the response to the displayName and scoredEmailAddresses of the 10 most relevant people.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mit dem $top-Parameter ändern. In diesem Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. This example uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Verwenden eines Filters zum Einschränken der AntwortUse 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.

Bei der folgenden Abfrage wird die Antwort auf die person-Instanzen mit der personType-Eigenschaft eingeschränkt, für die person als class und organizationUser als subclass festgelegt ist.The following query limits the response to person instances with the personType property being assigned person as class and organizationUser as subclass.

GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser'

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mit dem $top-Parameter ändern. In diesem Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. This example uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.onmicrosoft.com",
      "imAddress": "sip:LorrieF@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.onmicrosoft.com",
      "imAddress": "sip:MaynardD@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.onmicrosoft.com",
      "imAddress": "sip:DarrelH@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Auswählen der Felder, die in einer gefilterten Antwort zurückgegeben werdenSelect 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 wird displayName und scoredEmailAddresses von Personen angerufen, deren Anzeigenamen dem angegebenen Namen entspricht. In diesem Beispiel werden nur die Personen zurückgegeben, deren Anzeigename „Lorrie Frye“ lautet.The following example gets the displayName and scoredEmailAddresses of people whose display name equals the specified name. In this example, only people whose display name equals "Lorrie Frye" are returned.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses&$filter=displayName eq 'Lorrie Frye'

Das folgende Beispiel zeigt die Antwort.The following example shows the response.

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Durchsuchen von für andere Benutzer relevanten PersonenBrowse another user’s relevant people

Die folgende Anforderung ruft die für eine andere Person in der Organisation des angemeldeten Benutzers relevanten Personen ab.The following request gets the people most relevant to another person in the signed-in user's organization. Für diese Anforderung ist die Berechtigung People.Read.All erforderlich.This request requires the People.Read.All permission. Alle in den vorherigen Abschnitten beschriebenen Abfrageparameter gelten ebenfalls.All the query parameters described in the above sections apply as well.

In diesem Beispiel werden für Roscoe Seidel relevante Personen angezeigt.In this example, Roscoe Seidel's relevant people are displayed.

GET https://graph.microsoft.com/v1.0/users('roscoes@contoso.com')/people/

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mit dem $top-Parameter ändern. Im folgenden Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. The example below uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "56155636-703F-47F2-B657-C83F01F49BBC",
      "displayName": "Clifton Clemente",
      "givenName": "Clifton",
      "surname": "Clemente",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Director",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2106",
      "profession": "",
      "userPrincipalName": "CliftonC@contoso.onmicrosoft.com",
      "imAddress": "sip:CliftonC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.onmicrosoft.com",
          "relevanceScore": 20
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BF27D5A-AB4F-4C43-BED0-7DAD9EB0C1C4",
      "displayName": "Sheree Mitchell",
      "givenName": "Sheree",
      "surname": "Mitchell",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/2107",
      "profession": "",
      "userPrincipalName": "ShereeM@contoso.onmicrosoft.com",
      "imAddress": "sip:ShereeM@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.onmicrosoft.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0107"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "B3E5302D-EAF0-4E8B-8C6C-A2AE64B4B163",
      "displayName": "Vincent Matney",
      "givenName": "Vincent",
      "surname": "Matney",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Engineering",
      "companyName": null,
      "yomiCompany": "",
      "department": "Engineering",
      "officeLocation": "23/2102",
      "profession": "",
      "userPrincipalName": "VincentM@contoso.onmicrosoft.com",
      "imAddress": "sip:VincentM@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.onmicrosoft.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Durchsuchen von PersonenSearch people

Mit den Anforderungen in diesem Abschnitt können Sie nach Personen suchen, die für den angemeldeten Benutzer (/me) und andere Benutzer in der Organisation des angemeldeten Benutzers relevant sind. Für diese Anforderungen ist die People.Read-Berechtigung erforderlich. Eine Ausnahme stellt die Suche nach für andere Benutzer relevanten Personen, für die die People.Read.All-Berechtigung erforderlich ist. Standardmäßig gibt jede Antwort 10 Datensätze zurück, Sie können diese Einstellung jedoch mithilfe des $top-Parameters ändern.The requests in this section allow you to search for people relevant to the signed-in user (/me) and other users in the signed-in user’s organization. These requests require the People.Read permission, with the exception of searching other users’ relevant people, which requires People.Read.All. By default, each response returns 10 records, but you can change this by using the $top parameter.

Verwenden der Suche zum Auswählen von PersonenUse 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.

Mit der folgenden Abfrage werden die für /me relevanten Personen zurückgegeben, deren displayName oder „emailAddress“ mit dem Buchstaben „j“ beginnt.The following search query returns people relevant to /me whose displayName or *emailAddress" has a word that begins with the letter "j".

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jeder Antwort 10 Datensätze zurück. Sie können diese Einstellung mit dem $top-Parameter ändern. In diesem Beispiel wird $top verwendet, um die Anzahl der Antworten auf drei Datensätze einzuschränken.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. This example uses $top to limit the response to three records.

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

{
  "value": [
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Jan Travis",
      "givenName": "Jan",
      "surname": "Travis",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "VP Sales",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "19/3123",
      "profession": "",
      "userPrincipalName": "JanT@contoso.onmicrosoft.com",
      "imAddress": "sip:JanT@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.onmicrosoft.com",
          "relevanceScore": -12.297347783416837
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 732 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "C43BF05E-5B6B-4DCF-B2FC-0837B09E0FA9",
      "displayName": "Jacob Cazares (TAILSPIN)",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JacobC@tailspintoys.com",
          "relevanceScore": -12.298154282019846
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "PersonalContact"
      }
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Jewell Montgomery",
      "givenName": "Jewell",
      "surname": "Montgomery",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "JewellM@contoso.onmicrosoft.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.onmicrosoft.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Suchvorgänge implementieren einen Algorithmus für Fuzzyübereinstimmungen.Searches implement a fuzzy matching algorithm. Dabei werden Ergebnisse basierend auf einer exakten Übereinstimmung und auch zu Rückschlüssen zu der Absicht der Suche zurückgegeben.They will return results based on an exact match and also on inferences about the intent of the search. Verwenden wir als Beispiel einen Benutzer mit dem Anzeigenamen „Tyler Lee“ und der E-Mail-Adresse „tylerle@example.com“, der sich in der people-Sammlung des angemeldeten Benutzers befindet.For example, imagine a user with a display name of "Tyler Lee" and an email address of tylerle@example.com who is in the people collection of the signed-in user. Alle der folgenden Suchvorgänge geben den Benutzer „Tyler“ als eines der Ereignisse zurück.All of the following searches will return this user Tyler as one of the results.

GET https://graph.microsoft.com/v1.0/me/people?$search="tyler"                //matches both Tyler's name and email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle"              //matches Tyler's email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle@example.com"  //matches Tyler's email. Note the quotes to enclose '@'.
GET https://graph.microsoft.com/v1.0/me/people?$search="tiler"                //fuzzy match with Tyler's name
GET https://graph.microsoft.com/v1.0/me/people?$search="tyler lee"            //matches Tyler's name. Note the quotes to enclose the space.

Arbeiten mit der Implementierung von FeaturesWorking with feature implementation

Es muss eine öffentliche Beziehung zwischen dem Profilbesitzer und den anderen Personen geben, damit diese in der Liste des Profilbesitzers angezeigt werden.There must be a public relationship between the profile owner and the other people in order for those people to show up on the profile owner's list. Die folgende Abbildung zeigt einen Benutzer A, einen Index der Beziehungen mit anderen Benutzern (Benutzer B) und ein öffentliches Profil, in dem eine Teilmenge von Benutzerbeziehungen angezeigt wird.The following illustration shows a User A, an index of relationships with other users (User B), and a public profile showing a subset of user relationships.

Abbildung des Arbeitens mit Beziehungen

Die folgenden Beispiele zeigen öffentliche Beziehungen:The following are examples of public relationships:

  • Verbundene Personen im Organigramm: Vorgesetzter, direkter Mitarbeiter und Kollegen (haben den gleichen Vorgesetzten)Individuals connected in the org chart: Manager, Direct report, Peers (share the same manager)
  • Mitglieder einer öffentlichen Gruppe oder Verteilerliste mit weniger als 30 Personen.Members of a public group or distribution list with fewer than 30 people. Öffentliche Gruppen verfügen über Mitgliedschaftslisten, die im Verzeichnis verfügbar sind.Public groups have membership lists that are available in the directory.

Wenn der Profilbesitzer mit einer anderen Person kommuniziert und keine öffentlichen Beziehung zwischen ihnen besteht, z. B. eine Verbindung in einem Organigramm oder eine gemeinsame Gruppe, ist die Tatsache, dass diese miteinander kommuniziert haben, für andere nicht sichtbar.If the profile owner communicates with someone and there is no public relationship between them, such as an org chart connection or a group in common, the fact that they've been communicating will not be visible to others.

Die Rangfolge von Personen – d. h. die Reihenfolge, in der sie auf der Seite des Profilbesitzers angezeigt werden – wird von der privaten und öffentlichen Kommunikation zwischen dem Profilbesitzer und der Person in der Liste bestimmt.The ranking of people - that is, the order in which they appear on the profile owner's page - is determined by the private and public communication between the profile owner and the person on the list.

Beispiele für private Kommunikation sind:Examples of private communication include:

  • Gegenseitiges Senden von E-Mails, wobei sich der Name der anderen Person in der Zeile „An“ befindet.Sending emails to each other where the name of the other person is in the TO line
  • Einladen von Benutzern zu Besprechungen, indem ihr Name in die Kalendereinladung eingeschlossen wirdInviting users to meetings by including their name in the calendar invite

Beispiele für öffentliche Kommunikation sind:Examples of public interaction include:

  • Gegenseitiges Senden oder Empfangen von E-Mails als Teil einer öffentlichen GruppeSending or receiving emails to/from each other as part of a public group
  • Einladen von Benutzern zu Besprechungen als Teil einer Gruppe oder zu der mehr als X Personen eingeladen sindInviting users to meetings as part of group, or where more than X people are invited

Die Rangfolge ändert sich nicht basierend darauf, wer Benutzer A ist (die Person, die sich die Seite einer anderen Person ansieht).The ranking doesn’t change based on who User A is (the person looking at someone else's page). Die Rangfolge wird vom Interaktionslevel zwischen Benutzer B (Profilbesitzer) und Benutzer C (Person, die in der Liste des Profilbesitzers angezeigt wird) bestimmt.The ranking is determined by the interaction level between User B (profile owner) and User C (person showing up on profile owner's list).

Damit Benutzer C angezeigt wird, muss sich der Profilbesitzer in einer verhältnismäßig kleinen Gruppe/direkten Verbindung zu diesem Benutzer befinden, die öffentlich ist (was bedeutet, dass die Mitgliedschaftsliste im Verzeichnis verfügbar ist).In order for User C to appear, the profile owner must be in a relatively small group/DL with that user that is public (meaning the membership list is available in the directory).

Personen außerhalb der Organisation werden in der Liste des Profilbesitzers nicht angezeigt.People external to the organization will not show on the profile owner's list. Personen, mit denen sie per E-Mail kommunizieren oder sich treffen, die aber nicht Teil derselben Organisation sind, werden nicht im Abschnitt „Arbeitet mit“ angezeigt.People they email or meet with, but who are not part of the same organization, will not show up in the Working with section.