Benutzer abrufen
Namespace: microsoft.graph
Wichtig
APIs unter der /beta
Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .
Dient zum Abrufen der Eigenschaften und der Beziehungen des Benutzerobjekts.
Dieser Vorgang gibt standardmäßig nur eine Teilmenge der häufiger verwendeten Eigenschaften für jeden Benutzer zurück. Diese Standardeigenschaften werden im Abschnitt Eigenschaften aufgeführt. Um Eigenschaften abzurufen, die nicht standardmäßig zurückgegeben werden, führen Sie eine GET-Operation für den Benutzer aus, und geben Sie die Eigenschaften in einer $select
OData-Abfrageoption an. Da die user-Ressource Erweiterungen unterstützt, können Sie über den GET
-Vorgang auch benutzerdefinierte Eigenschaften und Erweiterungsdaten aus user-Instanzen abrufen.
Berechtigungen
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.
Berechtigungstyp | Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten) |
---|---|
Delegiert (Geschäfts-, Schul- oder Unikonto) | User.Read, User.ReadWrite, User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Delegiert (persönliches Microsoft-Konto) | User.Read, User.ReadWrite |
Anwendung | User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Tipp
- Das Aufrufen des
/me
-Endpunkts erfordert einen angemeldeten Benutzer und daher eine delegierte Berechtigung. Anwendungsberechtigungen werden bei der Benutzung des/me
-Endpunkts nicht unterstützt. - Die Berechtigung
User.Read
ermöglicht der App, das Profil zu lesen und Beziehungen wie Gruppenmitgliedschaft, Berichte und Vorgesetzte des angemeldeten Benutzers zu ermitteln.
HTTP-Anforderung
Für einen bestimmten Benutzer:
GET /me
GET /users/{id | userPrincipalName}
Tipp
- Wenn userPrincipalName mit einem
$
-Zeichen beginnt, schlägt die URL-Syntax/users/$x@y.com
der GET-Anforderung mit einem Fehlercode400 Bad Request
fehl. Dies liegt daran, dass diese Anforderungs-URL gegen die OData-URL-Konvention verstößt, wonach ein$
-Präfixzeichen nur bei Systemabfrageoptionen erwartet wird. Entfernen Sie den Schrägstrich (/) nach/users
, und schließen Sie den userPrincipalName in Klammern und einfache Anführungszeichen wie folgt ein:/users('$x@y.com')
. Beispiel:/users('$AdeleVance@contoso.com')
. - Um einen B2B-Benutzer mit userPrincipalName abzufragen, codieren Sie das Hashzeichen (#). Ersetzen Sie also das
#
-Symbol durch%23
. Beispiel:/users/AdeleVance_adatum.com%23EXT%23@contoso.com
.
Für den angemeldeten Benutzer:
GET /me
Optionale Abfrageparameter
Diese Methode unterstützt den $select
OData-Abfrageparameter, um bestimmte Benutzereigenschaften abzurufen, einschließlich derjenigen, die nicht standardmäßig zurückgegeben werden.
Erweiterungen und zugehörige Daten abrufen
Erweiterungstyp | Kommentare |
---|---|
onPremisesExtensionAttributes 1-15 | Wird nur mit $select zurückgegeben. |
Schemaerweiterungen | Wird nur mit $select zurückgegeben. |
Offene Erweiterungen | Wird nur durch die Operation Get open extension zurückgegeben. |
Verzeichniserweiterungen | Wird nur mit $select zurückgegeben. |
Anforderungsheader
Kopfzeile | Wert |
---|---|
Authorization | Bearer {token}. Erforderlich. |
Content-Type | application/json |
Anforderungstext
Geben Sie für diese Methode keinen Anforderungstext an.
Antwort
Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK
und ein user-Objekt im Antworttext zurückgegeben. Es werden die Standardeigenschaften zurückgegeben, es sei denn, Sie verwenden $select
, um bestimmte Eigenschaften anzugeben.
Diese Methode wird 202 Accepted
zurückgeben, wenn die Anforderung erfolgreich verarbeitet wurde, aber der Server mehr Zeit dazu benötigt, verbundene Hintergrundvorgänge abzuschließen.
Beispiel
Beispiel 1: Abrufen der Eigenschaften des angemeldeten Benutzers
Anforderung
GET https://graph.microsoft.com/beta/me
Antwort
Hier ist ein Beispiel für die Antwort. Hinweis: Das hier gezeigte Antwortobjekt wird möglicherweise zur besseren Lesbarkeit verkürzt.
HTTP/1.1 200 OK
Content-type: application/json
{
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.onmicrosoft.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}
Beispiel 2: Abrufen der Eigenschaften des angegebenen Benutzers
Anforderung
Das folgende Beispiel zeigt eine Anfrage.
GET https://graph.microsoft.com/beta/users/{id}
Antwort
Das folgende Beispiel zeigt die Antwort.
HTTP/1.1 200 OK
Content-type: application/json
{
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.onmicrosoft.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}
Beispiel 3: Verwenden von $select zum Abrufen bestimmter Eigenschaften eines Benutzers
Verwenden Sie zum Abrufen bestimmter Eigenschaften den OData-Abfrageparameter $select
. Um zum Beispiel displayName, givenName und postalCode und identities zurückzugeben, würden Sie Ihrer Abfrage folgendes hinzufügen: $select=displayName,givenName,postalCode,identities
Anforderung
GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode,identities
Antwort
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
"displayName": "Adele Vance",
"givenName": "Adele",
"postalCode": "98004",
"identities": [
{
"signInType": "userPrincipalName",
"issuer": "contoso.com",
"issuerAssignedId": "AdeleV@contoso.com"
}
]
}
Beispiel 4: Abrufen der benutzerdefinierten Sicherheitsattributzuweisungen des angegebenen Benutzers
Das folgende Beispiel ruft die benutzerdefinierten Sicherheitsattribute des angegebenen Benutzers ab.
Attribut Nr. 1
- Attributsatz:
Engineering
- Attribut:
Project
- Attributdatentyp: Auflistung von Zeichenfolgen
- Attributwert:
["Baker","Cascade"]
Attribut Nr. 2
- Attributsatz:
Engineering
- Attribut:
CostCenter
- Attributdatentyp: Sammlung von ganzzahligen Zahlen
- Attributwert:
[1001]
Attribut Nr. 3
- Attributsatz:
Engineering
- Attribut:
Certification
- Attributdatentyp: Boolesch
- Attributwert:
true
Attribut Nr. 4
- Attributsatz:
Marketing
- Attribut:
Level
- Attributdatentyp: Zeichenfolge
- Attributwert:
"Public"
Um benutzerdefinierte Sicherheitsattributzuweisungen abzurufen, muss dem aufrufenden Prinzipal die Rolle "Attributzuweisungsleser" oder "Attributzuweisungsadministrator" zugewiesen sein und ihm die Berechtigung CustomSecAttributeAssignment.Read.All oder CustomSecAttributeAssignment.ReadWrite.All gewährt werden.
Anforderung
GET https://graph.microsoft.com/beta/users/{id}?$select=customSecurityAttributes
Antwort
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
"customSecurityAttributes": {
"Engineering": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Project@odata.type": "#Collection(String)",
"Project": [
"Baker",
"Cascade"
],
"CostCenter@odata.type": "#Collection(Int32)",
"CostCenter": [
1001
],
"Certification": true
},
"Marketing": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Level": "Public"
}
}
}
Wenn dem Benutzer keine benutzerdefinierten Sicherheitsattribute zugewiesen sind oder der aufrufende Prinzipal keinen Zugriff hat, lautet die Antwort wie folgt:
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}
Beispiel 5: Abrufen des Werts einer Schemaerweiterung für einen Benutzer
In diesem Beispiel lautet die ID der Schemaerweiterung ext55gb1l09_msLearnCourses
.
Anforderung
GET https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses
Antwort
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
"ext55gb1l09_msLearnCourses": {
"@odata.type": "#microsoft.graph.ComplexExtensionValue",
"courseType": "Developer",
"courseName": "Introduction to Microsoft Graph",
"courseId": 1
}
}
Siehe auch
Feedback
Feedback senden und anzeigen für