Freigeben über


Benutzer auflisten

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.

Dient zum Abrufen einer Liste von Benutzerobjekten. Diese API gibt auch agentUser-Objekte zurück.

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der häufiger verwendeten Eigenschaften für jeden Benutzer und agentUser 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.

Wichtig

Gastbenutzer können diese API nicht aufrufen. Weitere Informationen zu den Berechtigungen für Mitglieds- und Gastbenutzer finden Sie unter Was sind die Standardbenutzerberechtigungen in Microsoft Entra ID?.

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 Berechtigung mit den geringsten Rechten Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) User.ReadBasic.All User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application User.Read.All User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Berechtigungen für bestimmte Szenarien

  • User-Mail.ReadWrite.All ist die Berechtigung mit den geringsten Berechtigungen zum Lesen und Schreiben der otherMails-Eigenschaft ; ermöglicht auch das Lesen einiger bezeichnerbezogener Eigenschaften für das Benutzerobjekt.
  • 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 bezeichnerbezogener Eigenschaften für das Benutzerobjekt.
  • 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 bezeichnerbezogener Eigenschaften für das Benutzerobjekt.
  • User.EnableDisableAccount.All + User.Read.All ist die Am wenigsten privilegierte Kombination von Berechtigungen zum Lesen und Schreiben der accountEnabled-Eigenschaft .

HTTP-Anforderung

Die folgende URL gibt eine Liste von user - und agentUser-Objekten zurück, wobei agentUser-Objekte eine @odata.type-Eigenschaft von #microsoft.graph.agentUserenthalten.

GET /users

Optionale Abfrageparameter

Diese Methode unterstützt OData-Abfrageparameter , um die Antwort anzupassen:

  • $count, $expand, $filter, $orderby, $search, $select, $top. $skip wird nicht unterstützt.
  • Um Agent-Benutzer aus dem Resultset zu filtern, verwenden Sie die isof Funktion: $filter=isof('microsoft.graph.agentUser') Gibt nur Agentbenutzer zurück, während $filter=not isof('microsoft.graph.agentUser') Agent-Benutzer ausgeschlossen sind.
  • Seitengrößenbeschränkungen: Die Standardseitengröße beträgt 100 Objekte. Die maximale Seitengröße beträgt 999 Objekte, außer wenn oder $filter=signInActivityverwendet $select=signInActivity wird, beträgt die maximale Seitengröße 500.
  • Einige Abfragen erfordern, dass der ConsistencyLevel-Header auf eventual und $countfestgelegt ist. Weitere Informationen finden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.
  • Die $count Parameter und $search sind in Azure AD B2C-Mandanten nicht verfügbar.

Erweiterungseigenschaften unterstützen auch Abfrageparameter wie folgt:

Erweiterungstyp Kommentare
onPremisesExtensionAttributes 1-15 Wird nur mit $select zurückgegeben. Unterstützt $filter (eq, ne und eq für null-Werte).
Schemaerweiterungen Wird nur mit $select zurückgegeben. Unterstützt $filter (eq, ne und eq für null-Werte).
Offene Erweiterungen Wird nur mit $expand zurückgegeben, d. h. users?$expand=extensions.
Verzeichniserweiterungen Wird nur mit $select zurückgegeben. Unterstützt $filter (eq, ne und eq für null-Werte).

Für agentUser-Objekte sind nicht anwendbare Eigenschaften immer null.

Bestimmte Eigenschaften können nicht innerhalb einer Benutzersammlung zurückgegeben werden. Die folgenden Eigenschaften werden nur beim Abrufen eines einzelnen Benutzers unterstützt: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.

Die folgenden Eigenschaften werden in persönlichen Microsoft-Konten nicht unterstützt und sind immer null: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
ConsistencyLevel schließlich. Diese Kopfzeile und $count sind erforderlich, wenn $search verwendet wird oder wenn $filter verwendet wird. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und eine Sammlung von Objekten vom Typ user und agentUser im Antworttext zurückgegeben. agentUser-Objekte enthalten eine @odata.type-Eigenschaft mit dem Wert #microsoft.graph.agentUser , um sie von Benutzerobjekten zu unterscheiden.

Wenn Sie versuchen, für die /users Auflistung zu verwenden$select, um Eigenschaften abzurufen, die innerhalb einer Auflistung nicht zurückgegeben werden können (z. B. die Anforderung ../users?$select=aboutMe), wird ein 501 Not Implemented Fehlercode zurückgegeben.

Beispiele

Beispiel 1: Alle Benutzenden abrufen

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Die Antwort enthält Agent-Benutzer.

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

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

{
  "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#@contoso.com"
    }
  ]
}

Beispiel 2: Nur Agent-Benutzer abrufen

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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

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

{
  "value":[
    {
      "@odata.type":"#microsoft.graph.agentUser",      
      "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#@contoso.com"
    }
  ]
}

Beispiel 3: Abrufen eines Benutzerkontos mithilfe eines Anmeldenamens

Suchen Sie ein Benutzerkonto unter Verwendung eines Anmeldenamens (auch bekannt als lokales Konto).

Hinweis: Beim Filtern nach issuerAssignedId müssen Sie issuer und issuerAssignedId angeben. Der Wert für issuer wird jedoch in bestimmten Szenarien ignoriert. Weitere Informationen zum Filtern nach Identitäten finden Sie unter objectIdentity-Ressourcentyp.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

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 'My B2C tenant')

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

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

Beispiel 4: Abrufen von Gastbenutzern (B2B) von einem bestimmten Mandanten oder einer bestimmten Domäne nach userPrincipalName

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Der UserPrincipalName-Wert für Gastbenutzer (B2B-Zusammenarbeit) enthält immer den Bezeichner "#EXT#". Beispielsweise ist AdeleV@adatum.comder userPrincipalName eines Benutzers in ihrem Basismandanten . Wenn Sie den Benutzer zur Zusammenarbeit in Ihrem Mandanten einladen, contoso.com, lautet dessen userPrincipalName in Ihrem Mandanten "AdeleV_adatum.com#EXT#@contoso.com".

Für diese Anforderung ist der ConsistencyLevel-Header auf eventual und die $count=true Abfragezeichenfolge erforderlich, da die Anforderung den operator endsWith enthält. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

ANMERKUNG: Sie müssen das reservierte Zeichen "#" im UserPrincipalName-Wert in der Anforderungs-URL als "%23" codieren. Weitere Informationen finden Sie unter Codieren von Sonderzeichen.

GET https://graph.microsoft.com/beta/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
ConsistencyLevel: eventual

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

Beispiel 5: Auflisten der letzten Anmeldezeit von Benutzern mit einem bestimmten Anzeigenamen

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

Hinweis

  • Details für die signInActivity-Eigenschaft erfordern eine Microsoft Entra ID P1- oder P2-Lizenz und die AuditLog.Read.All Berechtigung.
  • Wenn Sie oder $filter=signInActivity beim Auflisten von Benutzern angeben$select=signInActivity, beträgt die maximale Seitengröße für $top 500. Anforderungen mit $top einer Festlegung von mehr als 500 Seiten mit bis zu 500 Benutzern. Die signInActivity-Eigenschaft unterstützt $filter (eq, ne, not, ge, ), leaber nicht mit anderen filterbaren Eigenschaften.
GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity

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

{
  "@odata.context": "https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity",
  "value": [
    {
      "displayName": "Eric Solomon",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    }
  ]
}

Beispiel 6: Auflisten der letzten Anmeldezeit von Benutzern in einem bestimmten Zeitraum

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

Hinweis

Details für die signInActivity-Eigenschaft erfordern eine Microsoft Entra ID P1- oder P2-Lizenz und die AuditLog.Read.All Berechtigung.

GET https://graph.microsoft.com/beta/users?$filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z

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

{
  "@odata.context": "https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": "",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200",
        "lastSuccessfulSignInDateTime": "",
        "lastSuccessfulSignInRequestId": ""
      }
    }
  ]
}

Beispiel 7: Abrufen nur einer Anzahl von Benutzern

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $count in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

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

Antwort

Das folgende Beispiel zeigt die Antwort.

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

893

Beispiel 8: Verwenden von $filter und $top, um einen Benutzer mit einem Anzeigenamen abzurufen, der mit "a" beginnt, einschließlich der Anzahl der zurückgegebenen Objekte

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual und die $count=true-Abfragezeichenfolge festgelegt werden, da die Anforderung die Abfrageparameter $orderby und $filter aufweist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

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

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

{
  "@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#@contoso.com"
    }
  ]
}

Beispiel 9: Verwenden Sie $filter, um alle Benutzer mit einer E-Mail abzurufen, die mit ""a@contoso.com endet, einschließlich der Anzahl der zurückgegebenen Objekte, wobei die Ergebnisse nach userPrincipalName sortiert sind.

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual und die $count=true-Abfragezeichenfolge festgelegt werden, da die Anforderung die Abfrageparameter $orderby und $filter aufweist und den Operator endsWith verwendet. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

GET https://graph.microsoft.com/beta/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

Beispiel 10: Verwenden sie $search, um Benutzer mit Anzeigenamen abzurufen, die die Buchstaben "wa" enthalten, einschließlich der Anzahl der zurückgegebenen Objekte

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $search in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

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

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

{
  "@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 11: Verwenden sie $search, um Benutzer mit Anzeigenamen abzurufen, die die Buchstaben "wa" oder die Buchstaben "ad" enthalten, einschließlich der Anzahl der zurückgegebenen Objekte

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $search in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

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

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

{
  "@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":"contosoAdmin1",
      "mail":"'contosoadmin1@gmail.com",
      "mailNickname":"contosoadmin1_gmail.com#EXT#",
      "proxyAddresses":["SMTP:contosoadmin1@gmail.com"],
      "userPrincipalName":"contosoadmin1_gmail.com#EXT#@contoso.com"
    }
  ]
}

Beispiel 12: Verwenden von $filter zum Abrufen von Benutzern, denen eine bestimmte Lizenz zugewiesen ist

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $search in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Hinweis: Die Abfrageparameter $count und $search sind im Azure AD B2C-Mandanten derzeit nicht verfügbar.

GET https://graph.microsoft.com/beta/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

Antwort

Das folgende Beispiel zeigt die Antwort.

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}

Beispiel 13: Abrufen des Werts einer Schemaerweiterung für alle Benutzer

In diesem Beispiel lautet die ID der Schemaerweiterung ext55gb1l09_msLearnCourses.

Anforderung

GET https://graph.microsoft.com/beta/users?$select=ext55gb1l09_msLearnCourses

Antwort

In der folgenden Antwort ist die Schemaerweiterungseigenschaft ext55gb1l09_msLearnCourses in zwei der Benutzerobjekte nicht zugewiesen.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(ext55gb1l09_msLearnCourses)",
    "value": [
        {},
        {
            "ext55gb1l09_msLearnCourses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Developer",
                "courseName": "Introduction to Microsoft Graph",
                "courseId": 1
            }
        },
        {}
    ]
}

Hinweis: Sie können auch $filter auf die Schemaerweiterungseigenschaft anwenden, um Objekte abzurufen, bei denen eine Eigenschaft in der Sammlung mit einem angegebenen Wert übereinstimmt. Die Syntax lautet /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. Beispiel: GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. Die Operatoren eq und not werden unterstützt.

Beispiel 14: Auflisten aller Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung, die einem Wert entspricht

Das folgende Beispiel zeigt, wie sie alle Benutzer mit einer benutzerdefinierten Sicherheitsattributezuweisung auflisten, die einem Wert entspricht. Im Beispiel werden Benutzer mit einem benutzerdefinierten Sicherheitsattribute namens AppCountry mit einem Wert abgerufen, der gleich ist Canada. Beim Filterwert wird die Groß-/Kleinschreibung beachtet. Sie müssen in der Anforderung oder im Header hinzufügen ConsistencyLevel=eventual . Sie müssen auch einschließen $count=true , um sicherzustellen, dass die Anforderung ordnungsgemäß weitergeleitet wird.

Benutzer Nr. 1

  • Attributsatz: Marketing
  • Attribut: AppCountry
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["India","Canada"]

Benutzer 2

  • Attributsatz: Marketing
  • Attribut: AppCountry
  • Attributdatentyp: Auflistung von Zeichenfolgen
  • Attributwert: ["Canada","Mexico"]

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.

Beispiele für benutzerdefinierte Sicherheitsattributezuweisungen finden Sie unter Beispiele: Zuweisen, Aktualisieren, Auflisten oder Entfernen von benutzerdefinierten Sicherheitsattributen mithilfe des Microsoft Graph-API.

Anforderung

GET https://graph.microsoft.com/beta/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
ConsistencyLevel: eventual

Antwort

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 2,
    "value": [
        {
            "id": "dbaf3778-4f81-4ea0-ac1c-502a293c12ac",
            "displayName": "Jiya",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Datacenter@odata.type": "#Collection(String)",
                    "Datacenter": [
                        "India"
                    ]
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "India",
                        "Canada"
                    ],
                    "EmployeeId": "KX19476"
                }
            }
        },
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Beispiel 15: Auflisten aller Benutzer, deren Verwaltung eingeschränkt ist

Im folgenden Beispiel wird gezeigt, wie alle Benutzer aufgelistet werden, deren Verwaltung eingeschränkt ist.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

GET https://graph.microsoft.com/beta/users?$filter=isManagementRestricted eq true&$select=displayName,userPrincipalName

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName,userPrincipalName)",
  "value": [
    {
      "displayName": "Adele",
      "userPrincipalName": "Adele@contoso.com"
    },
    {
      "displayName": "Bob",
      "userPrincipalName": "Bob@contoso.com"
    }
  ]
}

Beispiel 16: Verwenden von $filter und endsWith, um Benutzer mit einer angegebenen Domäne der obersten Ebene in otherMails abzurufen

Anforderung

Das folgende Beispiel zeigt eine Anfrage. Für diese Anforderung muss die Kopfzeile ConsistencyLevel auf eventual festgelegt werden, da $count in der Anforderung enthalten ist. Weitere Informationen zur Verwendung von ConsistencyLevel und $countfinden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

GET https://graph.microsoft.com/beta/users?$filter=otherMails/any(x:endswith(x,'.edu'))&$count=true
ConsistencyLevel: eventual

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users",
    "@odata.nextLink": "https://graph.microsoft.com/beta/users?$filter=otherMails%2fany(x%3aendswith(x%2c%27.edu%27))&$skiptoken=m~AQAoOzAzNWVkMDQ1MTE5ZjRlMmNiM2Y2ODQzMmM4YzNiOWJiOzswOzA7Ow",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users?$select=signInActivity,cloudLicensing",
    "value": [
        {
            "displayName": "Isaiah Langer",
            "mail": "isaiahl@fineartschool.edu",
            "id": "0012cd20-3890-409e-9db3-afc3055ebe22"
        },
        {
            "displayName": "Adele Vance",
            "mail": "adelev@bellowscollege.edu",
            "id": "0012cd20-3890-409e-9db3-afc3055ebe22"
        }
    ]
}

Beispiel 17: Auflisten aller Nicht-Agent-Benutzer und Anzeigen nur des Anzeigenamens der Benutzer

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

GET https://graph.microsoft.com/beta/users?$count=true&$filter=not isof('microsoft.graph.agentUser')&$select=displayName

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(displayName)",
    "@odata.count": 3,
    "value": [
        {
            "displayName": "Adrian Smith",
            "id": "04b9f5a2-ee41-4d0e-b500-8de414d178c9"
        },
        {
            "displayName": "Lewis Richardson",
            "id": "0d03514d-35b0-4ffd-9ed9-d8052757e1c4"
        },
        {
            "displayName": "Fung Lu",
            "id": "146f9fcb-64c9-4b6e-b92f-bd4892fabdcd"
        }
  ]
}