Freigeben über


Benutzer abrufen

Namespace: microsoft.graph

Ruft die Eigenschaften und Beziehungen des Benutzerobjekts ab.

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.

Kunden über Microsoft Entra ID für Kunden können diesen API-Vorgang auch verwenden, um ihre Details abzurufen.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. 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

  • 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.
  • So lesen Sie die employeeLeaveDateTime-Eigenschaft :
    • In delegierten Szenarien benötigt der Administrator mindestens eine der folgenden Microsoft Entra Rollen: Lebenszyklusworkflowadministrator (geringste Rechte), Globaler Leser; der App muss die delegierte Berechtigung User-LifeCycleInfo.Read.All erteilt werden.
    • In reinen 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 Administrator die Rolle Attributzuweisungsadministrator zugewiesen werden, und der App muss die Berechtigung CustomSecAttributeAssignment.Read.All gewährt werden.
    • In reinen App-Szenarien mit Microsoft Graph-Berechtigungen muss der App die Berechtigung CustomSecAttributeAssignment.Read.All erteilt werden.

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 Fehlercode 400 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 $selectOData-Abfrageparameter zum Abrufen bestimmter Benutzereigenschaften, einschließlich der eigenschaften, die standardmäßig nicht zurückgegeben werden.

Standardmäßig wird nur ein begrenzter Satz von Eigenschaften zurückgegeben (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName).

Um einen alternativen Eigenschaftensatz zurückzugeben, müssen Sie den gewünschten Satz von user-Eigenschaften mithilfe des Odata-Abfrageparameters $select angeben. Um beispielsweise displayName, givenName und postalCode zurückzugeben, fügen Sie der Abfrage $select=displayName,givenName,postalCodeden folgenden Ausdruck hinzu.

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 die Authentifizierung und Autorisierung.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode 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.

Wenn ein Benutzer mit der ID nicht vorhanden ist, gibt diese Methode einen 404 Not Found Fehlercode zurück.

Beispiele

Beispiel 1: Standard-Benutzeranforderung

Anforderung

Standardmäßig wird nur ein begrenzter Satz von Eigenschaften zurückgegeben (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName). Dieses Beispiel zeigt die standardmäßige Anforderung und Antwort.

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd

Antwort

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

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "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: Anforderung des angemeldeten Benutzers

Sie können die Benutzerinformationen des angemeldeten Benutzers abrufen, indem Sie /users/{id | userPrincipalName} durch /me ersetzen.

Anforderung

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

Antwort

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

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "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. 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/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities

Antwort

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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 des Werts einer Schemaerweiterung für einen Benutzer

In diesem Beispiel lautet die ID der Schemaerweiterung ext55gb1l09_msLearnCourses.

Anforderung

GET https://graph.microsoft.com/v1.0/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/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
    "ext55gb1l09_msLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Developer",
        "courseName": "Introduction to Microsoft Graph",
        "courseId": 1
    }
}

Beispiel 5: Abrufen der benutzerdefinierten Sicherheitsattribute für einen Benutzer

Das folgende Beispiel zeigt, wie Sie die benutzerdefinierten Sicherheitsattribute für einen Benutzer abrufen.

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 Sicherheitsattributezuweisungen finden Sie unter Beispiele: Zuweisen, Aktualisieren, Auflisten oder Entfernen von benutzerdefinierten Sicherheitsattributen mithilfe der Microsoft Graph-API.

Anforderung

GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes

Antwort

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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, lautet die folgende Antwort:

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}