Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Namespace: microsoft.graph
Wichtig
Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.
Rufen Sie die Eigenschaften und Beziehungen eines Benutzerobjekts ab. Wenn die angegebene ID die eines agentUser ist, gibt die API die Eigenschaften des agentUser-Objekts zurück.
Dieser Vorgang gibt standardmäßig nur eine Teilmenge der häufiger verwendeten Eigenschaften 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 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.
Kunden über Microsoft Entra ID für Kunden können auch diesen API-Vorgang verwenden, um ihre Details abzurufen.
Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.
| Weltweiter Service | US Government L4 | US Government L5 (DOD) | China, betrieben von 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Berechtigungen
Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.
| Berechtigungstyp | Berechtigungen mit den geringsten Berechtigungen | Berechtigungen mit höheren Berechtigungen |
|---|---|---|
| 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 |
Hinweis
Die User.Read Berechtigung erlaubt der App nur das Auslesen des Profils und das Ermitteln von Beziehungen wie Gruppenmitgliedschaft, Berichte und Manager des angemeldeten Benutzers.
Berechtigungen für bestimmte Szenarien
- So lesen Sie die employeeLeaveDateTime-Eigenschaft :
- In delegierten Szenarien benötigt der angemeldete Benutzer mindestens eine der folgenden Microsoft Entra-Rollen: Lifecycle Workflows Administrator (niedrigste Rechte), globaler Leser; der App muss die delegierte Berechtigung User-LifeCycleInfo.Read.All erteilt werden.
- In Nur-App-Szenarien mit Microsoft Graph-Berechtigungen muss der App die Berechtigung User-LifeCycleInfo.Read.All erteilt werden.
- So lesen Sie die customSecurityAttributes-Eigenschaft :
- In delegierten Szenarien muss dem angemeldeten Benutzer die Rolle des Attributzuweisungsadministrators zugewiesen und der App die Berechtigung CustomSecAttributeAssignment.Read.All erteilt werden.
- In Nur-App-Szenarien mit Microsoft Graph-Berechtigungen muss der App die Berechtigung CustomSecAttributeAssignment.Read.All erteilt werden.
- User-Mail.ReadWrite.All ist die Berechtigung mit den geringsten Berechtigungen, um die Eigenschaft otherMails zu lesen und zu schreiben. Ermöglicht auch das Lesen einiger Bezeichner-bezogener Eigenschaften des Benutzerobjekts.
- User-PasswordProfile.ReadWrite.All ist die Berechtigung mit den geringsten Berechtigungen zum Lesen und Schreiben von Eigenschaften im Zusammenhang mit der Kennwortzurücksetzung. Ermöglicht auch das Lesen einiger Bezeichner-bezogener Eigenschaften des Benutzerobjekts.
- User-Phone.ReadWrite.All ist die Berechtigung mit den geringsten Berechtigungen zum Lesen und Schreiben der Eigenschaften businessPhones und mobilePhone . Ermöglicht auch das Lesen einiger Bezeichner-bezogener Eigenschaften des Benutzerobjekts.
- User.EnableDisableAccount.All + User.Read.All ist die am wenigsten privilegierte Kombination von Berechtigungen zum Lesen und Schreiben der accountEnabled-Eigenschaft .
HTTP-Anforderung
Für den angemeldeten Benutzer:
GET /me
Hinweis
Das Aufrufen des /me-Endpunkts erfordert einen angemeldeten Benutzer und daher eine delegierte Berechtigung. Anwendungsberechtigungen werden bei Verwendung des /me Endpunkts nicht unterstützt.
Für einen angegebenen Benutzer oder agentUser:
GET /users/{id | userPrincipalName}
Tipp
- Wenn userPrincipalName mit einem
$-Zeichen beginnt, schlägt die URL-Syntax/users/$x@y.comder GET-Anforderung mit einem Fehlercode400 Bad Requestfehl. Die Anforderung schlägt fehl, da die URL gegen die OData-URL-Konvention verstößt, die erwartet, dass nur Systemabfrageoptionen ein$Zeichen vorangestellt 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.
Optionale Abfrageparameter
Diese Methode unterstützt den $selectOData-Abfrageparameter , um bestimmte Eigenschaften abzurufen, einschließlich derjenigen, die standardmäßig nicht zurückgegeben werden. Erweiterungseigenschaften unterstützen auch Abfrageparameter wie folgt:
| 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. Erfahren Sie mehr über Authentifizierung und Autorisierung. |
Anforderungstext
Geben Sie keinen Anforderungstext für diese Methode an.
Antwort
Bei erfolgreicher Ausführung gibt diese Methode einen Antwortcode und ein200 OK user- oder agentUser-Objekt im Antworttext zurück. 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.
Wenn kein Objekt mit der ID vorhanden ist, gibt diese Methode einen 404 Not Found Fehlercode zurück.
Beispiel
Beispiel 1: Abrufen der Eigenschaften des angemeldeten Benutzers oder des authentifizierten AgentUsers
Anforderung
GET https://graph.microsoft.com/beta/me
Antwort
Das folgende Beispiel zeigt die Antwort.
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 200 OK
Content-type: application/json
{
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@contoso.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.com",
"id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}
Beispiel 2: Abrufen der Eigenschaften des angegebenen Benutzers
Anforderung
Das folgende Beispiel zeigt eine Anfrage. Wenn die angegebene ID die eines agentUser ist, gibt die API die Eigenschaften des agentUser-Objekts zurück.
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.com",
"mobilePhone": "+1 425 555 0109",
"officeLocation": "18/2111",
"preferredLanguage": "en-US",
"surname": "Vance",
"userPrincipalName": "AdeleV@contoso.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. Fügen Sie Ihrer Abfrage beispielsweise den folgenden Abfrageausdruck hinzu, um beispielsweise displayName, givenName, postalCode und Identitäten zurückzugeben $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 für einen Benutzer
Im folgenden Beispiel wird gezeigt, wie die benutzerdefinierten Sicherheitsattributzuweisungen für einen Benutzer abgerufen werden.
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:
EmployeeId - Attributdatentyp: Zeichenfolge
- Attributwert:
"QN26904"
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.
Weitere Beispiele für benutzerdefinierte Sicherheitsattributzuweisungen finden Sie unter Beispiele: Zuweisen, Aktualisieren, Auflisten oder Entfernen benutzerdefinierter Sicherheitsattributzuweisungen mithilfe der Microsoft Graph-API.
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": {
"Marketing": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"EmployeeId": "QN26904"
},
"Engineering": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Project@odata.type": "#Collection(String)",
"Project": [
"Baker",
"Cascade"
],
"CostCenter@odata.type": "#Collection(Int32)",
"CostCenter": [
1001
],
"Certification": true
}
}
}
Wenn dem Benutzer keine benutzerdefinierten Sicherheitsattribute zugewiesen sind oder der aufrufende Prinzipal keinen Zugriff hat, zeigt der folgende Block die Antwort an:
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
}
}