Freigeben über

Die Personen-API verwenden, um Informationen über die für Sie relevantesten Personen zu erhalten

  • Artikel

Microsoft Graph-Anwendungen können die Personen-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, aus dem Verzeichnis einer Organisation und Personen aus kürzlichen Unterhaltungen sein.

Neben der Generierung dieser Erkenntnisse bietet die Personen-API auch Unterstützung für die Fuzzyübereinstimmung bei Suchvorgängen sowie die Möglichkeit, eine Liste der für einen Benutzer relevanten Personen in der Organisation des angemeldeten Benutzers abzurufen.

Die Personen-API ist nützlich für Personenauswahlszenarien, z. B. das Verfassen einer E-Mail oder das Erstellen einer Besprechung. Sie können die Personen-API beispielsweise beim Verfassen von E-Mails verwenden.

Einschließen einer Person als relevant oder „arbeiten mit“

Damit eine Person in Delve für einen Profilbesitzer als „relevant für“ oder „arbeiten mit“ einbezogen, auf der Profilkarte des Besitzers angezeigt oder von der Personen-API zurückgegeben wird, muss eine öffentliche Beziehung zwischen der Person und dem Profilbesitzer bestehen. 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.

Abbildung des Arbeitens mit Beziehungen

Die folgenden Beispiele zeigen öffentliche Beziehungen:

  • Verbundene Personen im Organigramm: Vorgesetzter, direkter Mitarbeiter und Peers (haben den gleichen Vorgesetzten)
  • Mitglieder einer öffentlichen Gruppe oder Verteilerliste mit weniger als 30 Personen. Öffentliche Gruppen verfügen über Mitgliedschaftslisten, die im Verzeichnis verfügbar sind.

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 sie miteinander kommuniziert haben, für andere nicht sichtbar.

Die Rangfolge der Personen – d. h. die Reihenfolge, in der sie auf der Seite des Profilbesitzers angezeigt werden – wird durch die öffentliche Kommunikation zwischen dem Profilbesitzer und der Person in der Liste bestimmt.

Beispiele für öffentliche Kommunikation sind:

  • Gegenseitiges Senden oder Empfangen von E-Mails als Teil einer öffentlichen Gruppe
  • Einladen von Benutzern zu Besprechungen als Teil einer Gruppe oder zu der mehr als X Personen eingeladen sind

Die Rangfolge ändert sich nicht basierend darauf, wer Benutzer A ist (die Person, die sich die Seite einer anderen Person ansieht). Die Rangfolge wird vom Interaktionslevel zwischen Benutzer B (Profilbesitzer) und Benutzer C (Person, die in der Liste des Profilbesitzers angezeigt wird) bestimmt.

Damit Benutzer C angezeigt wird, muss sich der Profilbesitzer in einer verhältnismäßig kleinen Gruppe oder Verteilerliste mit diesem Benutzer befinden, die öffentlich ist (was bedeutet, dass die Mitgliedschaftsliste im Verzeichnis verfügbar ist).

Personen außerhalb der organization werden nicht in der Liste des Profilbesitzers angezeigt. Personen, die sie per E-Mail senden oder sich treffen, aber nicht Teil desselben organization sind, werden auch nicht als Personen angezeigt, mit denen der Besitzer zusammenarbeitet.

Deaktivieren von „arbeiten mit“

Administratoren können die Anzeige oder Rückgabe von Personen, die für einen Profilbesitzer relevant sind, auf zwei Ebenen verwalten:

  • Für eine Organisation:
    • Aktivieren für die gesamte Organisation. Dies ist die Standardeinstellung.
    • Deaktivieren für die gesamte Organisation, mit Ausnahme des Profilbesitzers.
  • Für eine Microsoft Entra Gruppe im organization:
    • Deaktivieren Sie für eine angegebene Microsoft Entra Gruppe. Dies ist nützlich, um das "Arbeiten mit" für eine organization mit Ausnahme von Mitgliedern in der Microsoft Entra-Gruppe zu aktivieren.

Weitere Informationen finden Sie unter benutzerdefinierte Datenschutzsteuerung für Personenerkenntnisse.

Authorization

Um die Personen-API in Microsoft Graph aufzurufen, benötigt Ihre App die entsprechenden Berechtigungen:

  • People. Read – Verwenden, um allgemeine Personen-API-Aufrufe durchzuführen, z. B. https://graph.microsoft.com/v1.0/me/people/. People.Read erfordert die Zustimmung des Endbenutzers.
  • 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 erfordert die Zustimmung des Administrators.

Durchsuchen von Personen

Mit den Anforderungen in diesem Abschnitt werden die Personen abgerufen, die für den angemeldeten Benutzer (/me) oder für einen bestimmten Benutzer im organization des angemeldeten Benutzers am relevantesten sind. Diese Anforderungen erfordern die Personen. Lesen oder Personen. Read.All-Berechtigung. Standardmäßig gibt jede Antwort 10 Datensätze zurück, aber Sie können dies mithilfe des abfrageparameters $top ändern.

Abrufen einer Sammlung relevanter Personen

Mit der folgenden Anforderung werden die für den angemeldeten Benutzer relevantesten Personen (/me) auf Grundlage von Kommunikations- und Zusammenarbeitsmustern sowie Geschäftsbeziehungen abgerufen.

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jede Antwort 10 Datensätze zurück. Sie können dies mithilfe des abfrageparameters $top ändern. In diesem Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.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.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.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.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Anfordern einer nachfolgenden Seite mit Personen

Wenn die erste Antwort nicht die vollständige Liste der relevanten Personen enthält, können Sie eine zweite Anforderung mit $top und $skip stellen, um zusätzliche Seiten mit Informationen anzufordern. Wenn die vorherige Anforderung zusätzliche Informationen enthält, erhält die folgende Anforderung die nächste Seite der Personen vom Server.

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jede Antwort 10 Datensätze zurück. Sie können dies mithilfe des abfrageparameters $top ändern. In diesem Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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.com",
      "imAddress": "sip:FelixC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.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.com",
      "imAddress": "sip:LenoraR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.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.com",
      "imAddress": "sip:ManuelC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Sortieren der Antwort

Standardmäßig werden die Personen in der Antwort nach ihrer Relevanz für Ihre Abfrage sortiert. Sie können die Reihenfolge der Personen in der Antwort ändern, indem Sie den Parameter $orderby verwenden. Diese Abfrage wählt die personen aus, die für Sie am relevantesten sind, sortiert sie nach ihrem displayName und gibt dann die ersten 10 Personen in der sortierten Liste zurück.

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jede Antwort 10 Datensätze zurück. Sie können dies ändern, indem Sie den Parameter $top verwenden. Im folgenden Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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.com",
      "imAddress": "sip:AdrianaR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.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.com",
      "imAddress": "sip:AlyceC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.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.com",
      "imAddress": "sip:AlyssaC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.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 Felder

Sie können die Anzahl der Personen ändern, die in der Antwort zurückgegeben wird, indem Sie den $top-Parameter festlegen.

Im folgenden Beispiel werden die 1.000 Personen angefordert, die für am relevantesten sind /me. Die Anforderung schränkt auch die Menge der vom Server zurückgesendeten Daten ein, indem nur der displayName der Person angefordert wird.

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

Das folgende Beispiel zeigt die Antwort.

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"
    }
  ]
}

Arten von enthaltenen Ergebnissen

Standardmäßig liefert Microsoft Graph nur Postfachergebnisse, bei denen es sich um Ihre gespeicherten Kontakte oder Personen handelt, mit denen Sie am ehesten interagieren. Um organisationsweite Verzeichnisergebnisse abzurufen, geben Sie einen HTTP-Header an (siehe Abbildung).

"X-PeopleQuery-QuerySources: Mailbox,Directory”

Auswählen der zurückgegebenen Felder

Sie können die vom Server zurückgegebene Datenmenge begrenzen, indem Sie den Parameter $select verwenden, um ein oder mehrere Felder auszuwählen. Das @odata.id Feld wird immer zurückgegeben.

Im folgenden Beispiel wird die Antwort auf displayName und scoredEmailAddresses der 10 relevantesten Personen begrenzt.

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jede Antwort 10 Datensätze zurück. Sie können dies mit dem Parameter $top ändern. In diesem Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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

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

Verwenden eines Filters zum Einschränken der Antwort

Sie können den $filter-Parameter zum Einschränken der Antwort auf diejenigen Personen einschränken, deren Datensätze die angegebenen Kriterien enthalten.

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.

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 jede Antwort 10 Datensätze zurück. Sie können dies mit dem Parameter $top ändern. In diesem Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.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.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.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.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.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 werden

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.

Im folgenden Beispiel werden displayName und scoredEmailAddresses von Personen abgerufen, deren Anzeigename dem angegebenen Namen entspricht. In diesem Beispiel werden nur Personen zurückgegeben, deren Anzeigename "Lorrie Frye" entspricht.

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

Das folgende Beispiel zeigt die Antwort.

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

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

Durchsuchen von für andere Benutzer relevanten Personen

Mit der folgenden Anforderung werden die Personen ermittelt, die für eine andere Person in der Organisation des angemeldeten Benutzers am relevantesten sind, wie in der Implementierung des Features „Arbeiten-mit“ beschrieben. Für diese Anforderung ist die Berechtigung People.Read.All erforderlich. Alle in den vorherigen Abschnitten beschriebenen Abfrageparameter gelten ebenfalls.

In diesem Beispiel werden für Roscoe Seidel relevante Personen angezeigt.

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jede Antwort 10 Datensätze zurück. Sie können dies mit dem Parameter $top ändern. Im folgenden Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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.com",
      "imAddress": "sip:CliftonC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.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.com",
      "imAddress": "sip:ShereeM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.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.com",
      "imAddress": "sip:VincentM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Durchsuchen von Personen

Mit den Anforderungen in diesem Abschnitt können Sie nach Personen suchen, die für den angemeldeten Benutzer (/me) und andere Benutzer im organization des angemeldeten Benutzers relevant sind. Diese Anforderungen erfordern die Personen. Leseberechtigung, mit Ausnahme der Suche nach relevanten Personen anderer Benutzer, für die Personen erforderlich ist. Read.All. Standardmäßig gibt jede Antwort 10 Datensätze zurück, aber Sie können dies mit dem Parameter $top ändern.

Verwenden der Suche zum Auswählen von Personen

Verwenden Sie den $search-Parameter zum Auswählen von Personen, die bestimmte Kriterien erfüllen.

Mit der folgenden Suchabfrage werden die für /me relevanten Personen zurückgegeben, deren displayName oder emailAddress mit dem Buchstaben „j“ beginnt.

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

Das folgende Beispiel zeigt die Antwort. Standardmäßig gibt jede Antwort 10 Datensätze zurück. Sie können dies mit dem Parameter $top ändern. In diesem Beispiel wird $top verwendet, um die Antwort auf drei Datensätze zu beschränken.

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.com",
      "imAddress": "sip:JanT@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.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.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Suchvorgänge implementieren einen Algorithmus für Fuzzyübereinstimmungen. Sie geben Ergebnisse basierend auf einer genauen Übereinstimmung und auch auf Rückschlüssen über die Absicht der Suche zurück. 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. Alle folgenden Suchvorgänge geben diesen Benutzer Tyler als eines der Ergebnisse zurück.

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.