Benutzer auflistenList users

Namespace: microsoft.graphNamespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

Dient zum Abrufen einer Liste von Benutzerobjekten.Retrieve a list of user objects.

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der häufiger verwendeten Eigenschaften für jeden Benutzer zurück.This operation returns by default only a subset of the more commonly used properties for each user. Diese Standardeigenschaften werden im Abschnitt Eigenschaften aufgeführt.These default properties are noted in the Properties section. 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.To get properties that are not returned by default, do a GET operation for the user and specify the properties in a $select OData query option.

BerechtigungenPermissions

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.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All, Auditlogs.Read.AllUser.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All, Auditlogs.Read.All
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Nicht unterstütztNot supported.
AnwendungApplication User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Auditlogs.Read.AllUser.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Auditlogs.Read.All

HTTP-AnforderungHTTP request

GET /users

Optionale AbfrageparameterOptional query parameters

Diese Methode unterstützt die OData-Abfrageparameter zur Unterstützung der Anpassung der Antwort, einschließlich $search , $count und $filter .This method supports the OData query parameters to help customize the response, including $search, $count, and $filter. Sie können $search die DisplayName -Eigenschaft verwenden.You can use $search on the displayName property. Wenn Elemente für diese Ressource hinzugefügt oder aktualisiert werden, werden Sie speziell für die Verwendung mit den $count -und $search Abfrageparametern indiziert.When items are added or updated for this resource, they are specially indexed for use with the $count and $search query parameters. Es kann eine geringfügige Verzögerung zwischen dem Hinzufügen oder Aktualisieren eines Elements und der Verfügbarkeit im Index auftreten.There can be a slight delay between when an item is added or updated and when it is available in the index.

AnforderungsheaderRequest headers

KopfzeileHeader WertValue
AuthorizationAuthorization Bearer {token} (erforderlich)Bearer {token} (required)
ConsistencyLevelConsistencyLevel eventuelle.eventual. Diese Kopfzeile und $count sind bei Verwendung $search von oder bei Verwendung $filter mit dem $orderby Abfrageparameter erforderlich.This header and $count are required when using $search, or when using $filter with the $orderby query parameter. Es wird ein Index verwendet, der möglicherweise nicht auf dem neuesten Stand der letzten Änderungen am Objekt ist.It uses an index that may not be up-to-date with recent changes to the object.

AnforderungstextRequest body

Geben Sie für diese Methode keinen Anforderungstext an.Do not supply a request body for this method.

AntwortResponse

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und eine Sammlung von user-Objekten im Antworttext zurückgegeben.If successful, this method returns a 200 OK response code and collection of user objects in the response body.

BeispieleExamples

Beispiel 1: Abrufen aller BenutzerExample 1: Get all users

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "value":[
    {
      "displayName":"contoso1",
      "mail":"'contoso1@gmail.com",
      "mailNickname":"contoso1_gmail.com#EXT#",
      "otherMails":["contoso1@gmail.com"],
      "proxyAddresses":["SMTP:contoso1@gmail.com"], 
      "userPrincipalName":"contoso1_gmail.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Beispiel 2: Abrufen eines Benutzerkontos mithilfe eines AnmeldenamensExample 2: Get a user account using a sign-in name

Suchen Sie ein Benutzerkonto unter Verwendung eines Anmeldenamens (auch bekannt als lokales Konto).Find a user account using a sign-in name (also known as a local account).

Hinweis

Beim Filtern nach identities müssen Sie issuer und issuerAssignedId angeben.When filtering on identities, you must supply both issuer and issuerAssignedId.

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'contoso.onmicrosoft.com')

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "value": [
    {
      "displayName": "John Smith"
    }
  ]
}

Beispiel 3: Abrufen von Benutzern einschließlich der letzten AnmeldezeitExample 3: Get users including their last sign-in time

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?$select=displayName,userPrincipalName,signInActivity

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName,userPrincipalName,signInActivity)",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2017-09-04T15:35:02Z",
        "lastSignInRequestId": "c7df2760-2c81-4ef7-b578-5b5392b571df"
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2017-07-29T02:16:18Z",
        "lastSignInRequestId": "90d8b3f8-712e-4f7b-aa1e-62e7ae6cbe96"
      }
    }
  ]
}

Beispiel 4: Auflisten der letzten Anmeldezeit von Benutzern mit einem bestimmten AnzeigenamenExample 4: List the last sign-in time of users with a specific display name

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity",
  "value": [
    {
      "displayName": "Eric Solomon",
      "signInActivity": {
        "lastSignInDateTime": "2017-09-04T15:35:02Z",
        "lastSignInRequestId": "c7df2760-2c81-4ef7-b578-5b5392b571df"
      }
    }
  ]
}

Beispiel 5: Auflisten der letzten Anmeldezeit von Benutzern in einem bestimmten ZeitraumExample 5: List the last sign-in time of users in a specific time range

AnfrageRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2019-06-01T00:00:00Z

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2019-06-01T00:00:00Z",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2019-05-04T15:35:02Z",
        "lastSignInRequestId": "c7df2760-2c81-4ef7-b578-5b5392b571df"
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2019-04-29T02:16:18Z",
        "lastSignInRequestId": "90d8b3f8-712e-4f7b-aa1e-62e7ae6cbe96"
      }
    }
  ]
}

Beispiel 6: Abrufen einer Anzahl von BenutzernExample 6: Get only a count of users

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users/$count
ConsistencyLevel: eventual

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

HTTP/1.1 200 OK
Content-type: text/plain

893893

Beispiel 7: Verwenden Sie $Filter und $Top, um einen Benutzer mit einem Anzeigenamen zu erhalten, der mit "a" beginnt, einschließlich der Anzahl zurückgegebener Objekte.Example 7: Use $filter and $top to get one user with a display name that starts with 'a' including a count of returned objects

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "otherMails":["a@contoso.com"],
      "proxyAddresses":["SMTP:a@contoso.com"],
      "userPrincipalName":"a_contoso.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Beispiel 8: Verwenden Sie $Search, um Benutzer mit Anzeigenamen abzurufen, die die Buchstaben "WA" enthalten, einschließlich der Anzahl der zurückgegebenen Objekte.Example 8: Use $search to get users with display names that contain the letters 'wa' including a count of returned objects

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Beispiel 9: Verwenden Sie $Search, um Benutzer mit Anzeigenamen abzurufen, die die Buchstaben "WA" oder die Buchstaben "an" enthalten, einschließlich der Anzahl der zurückgegebenen Objekte.Example 9: Use $search to get users with display names that contain the letters 'wa' or the letters 'to' including a count of returned objects

AnforderungRequest

Nachfolgend sehen Sie ein Beispiel der Anforderung.The following is an example of the request.

GET https://graph.microsoft.com/beta/users?$search="displayName:wa" OR "displayName:to"&$orderbydisplayName&$count=true
ConsistencyLevel: eventual

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.The following is an example of the response.

Hinweis: Das hier gezeigte Antwortobjekt wurde möglicherweise zur besseren Lesbarkeit gekürzt. Ein tatsächlicher Aufruf gibt alle Eigenschaften zurück.Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contoso1",
      "mail":"'contoso1@gmail.com",
      "mailNickname":"contoso1_gmail.com#EXT#",
      "proxyAddresses":["SMTP:contoso1@gmail.com"], 
      "userPrincipalName":"contoso1_gmail.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}