Fonctionnalités de requête avancées sur les objets Microsoft Entra ID

À mesure que Microsoft Entra continue d’offrir davantage de fonctionnalités et d’améliorations en matière de stabilité, de disponibilité et de performances, Microsoft Graph continue également d’évoluer et de s’adapter pour accéder efficacement aux données. L’une des méthodes consiste à prendre en charge de plus en plus les fonctionnalités de requête avancées de Microsoft Graph sur différents objets Microsoft Entra ID, également appelés objets d’annuaire, et leurs propriétés. Par exemple, l’ajout d’opérateurs Not (not), Non égaux (ne) et se termine avec (endsWith) sur le paramètre de $filter requête.

Le moteur de requête Microsoft Graph utilise un magasin d’index pour répondre aux demandes de requête. Pour ajouter la prise en charge de fonctionnalités de requête supplémentaire sur certaines propriété, celles-ci sont désormais indexées dans un serveur distinct. Cette indexation distincte permet Microsoft Entra ID d’augmenter la prise en charge et d’améliorer les performances des requêtes. Toutefois, ces fonctionnalités de requête avancées ne sont pas disponibles par défaut, mais le demandeur doit également définir l’en-tête ConsistencyLevel sur eventualet, à l’exception de $search, utiliser le paramètre de $count requête. L’en-tête ConsistencyLevel et $count font référence aux paramètres de requête avancée.

Par exemple, pour récupérer uniquement les comptes d’utilisateur inactifs, vous pouvez exécuter l’une de ces requêtes qui utilisent le paramètre de requête $filter.

Option 1 : Utilisez le paramètre de $filter requête avec l’opérateur eq . Cette requête fonctionne par défaut, c’est-à-dire qu’elle ne nécessite pas les paramètres de requête avancés.

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false

Option 2 : Utilisez le paramètre de $filter requête avec l’opérateur ne . Cette requête n’est pas prise en charge par défaut, car l’opérateur ne est uniquement pris en charge dans les requêtes avancées. Par conséquent, vous devez ajouter l’en-tête ConsistencyLevel défini sur eventualet utiliser la chaîne de $count=true requête.

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual

Microsoft Entra ID objets (répertoire) qui prennent en charge les fonctionnalités de requête avancées

Ces fonctionnalités de requête avancées sont prises en charge uniquement sur les objets d’annuaire et leurs relations, y compris les objets fréquemment utilisés suivants :

Objet Relations
administrativeUnit
  • membres
  • application
  • propriétaires
  • appRoleAssignment -
    appareil
  • memberOf
  • transitiveMemberOf
  • registeredUsers
  • registeredOwners
  • groupe
  • membres
  • transitiveMembers
  • memberOf
  • transitiveMemberOf
  • propriétaires
  • appRoleAssignments
  • oAuth2PermissionGrant (octrois d’autorisations déléguées) -
    orgContact
  • memberOf
  • transitiveMemberOf
  • servicePrincipal
  • memberOf
  • transitiveMemberOf
  • appRoleAssignments
  • appRoleAssignmentsTo
  • oAuth2PermissionGrant
  • user
  • memberOf
  • transitiveMemberOf
  • ownedObjects
  • registeredDevices
  • ownedDevices
  • transitiveManagers
  • directReports
  • transitiveReports
  • appRoleAssignments
  • oAuth2PermissionGrant
  • Scénarios de requête nécessitant des fonctionnalités de requête avancées

    Le tableau suivant répertorie les scénarios de requête sur des objets annuaire qui sont uniquement pris en charge dans des requêtes avancées :

    Description Exemple
    Utilisation de $count en tant que segment d’URL GET~/groups/$count
    Utilisation de $count comme paramètre de chaîne de requête GET~/servicePrincipals?$count=true
    Utilisation de $count dans une expression $filter GET~/users?$filter=assignedLicenses/$count eq 0&$count=true
    Utilisation de $search GET~/applications?$search="displayName:Browser"
    Utilisation de $orderby sur certaines propriétés GET~/applications?$orderby=displayName&$count=true
    Utilisation de $filter avec l’opérateur endsWith GET~/users?$count=true&$filter=endsWith(mail,'@outlook.com')
    Utilisateur de $filter et $orderby dans la même requête GET../applications?$orderby=displayName&$filter=startsWith( displayName, 'Box')&$count=true
    Utilisation de $filter avec les opérateurs startsWith sur des propriétés spécifiques. GET~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true
    Utilisation de $filter avec les opérateurs ne et not GET~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true
    Utilisation de $filter avec les opérateurs not et startsWith GET~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true
    Utilisation de $filter sur une collection avec l’opérateur endsWith GET~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses
    Utilisation de la conversion OData avec la liste des membres transitifs GET~/me/transitiveMemberOf/microsoft.graph.group?$count=true

    Remarque

    • L’utilisation simultanée de $filter et $orderby est uniquement pris en charge par les requêtes avancées.
    • $expand n’est actuellement pas pris en charge avec les requêtes avancées.
    • Ces fonctionnalités de requête avancée ne sont pas disponibles chez les clients Azure AD B2C.
    • Pour utiliser des fonctionnalités de requête avancées dans les requêtes par lots, spécifiez l’en-tête ConsistencyLevel dans le corps JSON de la demande POST .

    Prise en charge du filtrage par propriétés des objets Microsoft Entra ID (répertoire)

    Les propriétés d’objets annuaire se comportent différemment dans leur prise en charge pour des paramètres de requête. Les scénarios suivants sont courants pour les objets annuaire :

    • Les requêtes prises en charge par défaut fonctionnent également avec des paramètres de requête avancés, mais la réponse sera finalement cohérente.
    • inL’opérateur est pris en charge par défaut chaque fois que eq l’opérateur est pris en charge par défaut.
    • L’opérateur endsWith est pris en charge uniquement avec les paramètres de requête avancés par les propriétés mail, otherMails, userPrincipalName et proxyAddresses .
    • L’obtention de collections vides (/$count eq 0, /$count ne 0) et de collections avec moins d’un objet (/$count eq 1, /$count ne 1) est prise en charge uniquement avec des paramètres de requête avancés.
    • Les not opérateurs de négation et ne sont pris en charge uniquement avec les paramètres de requête avancés.
      • Toutes les propriétés qui prennent en charge l’opérateur eq prennent également en charge les ne opérateurs ou not .
      • Pour les requêtes utilisant l’opérateur lambda any, utilisez l’opérateur not. Voir Filtrage en utilisant des opérateurs lambda.

    Les tableaux suivants résument la prise en charge des $filter opérateurs par les propriétés des objets d’annuaire et indiquent où l’interrogation est prise en charge par le biais de fonctionnalités de requête avancées.

    Legend

    • Fonctionne par défaut. Ne nécessite pas de paramètres de requête avancés. L’opérateur $filter fonctionne par défaut pour cette propriété.
    • Nécessite des paramètres de requête avancés. L’opérateur $filternécessite desparamètres de requête avancés, qui sont les suivants :
      • En-tête ConsistencyLevel=eventual
      • Chaîne de requête $count=true
    • Non pris en charge. L’opérateur $filter n’est pas pris en charge sur cette propriété. Envoyez-nous vos commentaires pour demander la prise en charge de cette propriété $filter pour vos scénarios.
    • Les cellules vides indiquent que la requête n’est pas valide pour cette propriété.
    • La colonne valeur nulle indique que la propriété peut avoir la valeur Null et peut être filtrée à l’aide de null.
    • Les propriétés qui ne sont pas répertoriées ici ne prennent pas en charge $filter du tout.

    Propriétés des unités administratives

    Propriété eq startsWith eq Null
    description Avancé Avancé Avancé
    displayName Par défaut Par défaut Avancé
    isMemberManagementRestricted Par défaut NotSupported
    scopedRoleMembers/any(s :s/id) Par défaut

    Propriétés de l’application

    Propriété eq startsWith ge/le eq Null
    appId Par défaut NotSupported
    createdDateTime Par défaut Par défaut Avancé
    createdOnBehalfOf/id Par défaut
    description Avancé Avancé Avancé
    disabledByMicrosoftStatus Par défaut NotSupported
    displayName Par défaut Par défaut Avancé
    federatedIdentityCredentials/any(f :f/issuer) Avancé Avancé NotSupported
    federatedIdentityCredentials/any(f :f/name) Avancé Avancé NotSupported
    federatedIdentityCredentials/any(f :f/subject) Avancé Avancé NotSupported
    identifierUris/any(p:p) Par défaut Par défaut
    info/logoUrl NotSupported NotSupported Avancé
    info/termsOfServiceUrl Avancé NotSupported NotSupported
    notes Avancé Avancé Avancé
    publicClient/redirectUris/any(p:p) Avancé Avancé
    publisherDomain Par défaut Par défaut NotSupported
    requiredResourceAccess/any(r:r/resourceAppId) Avancé NotSupported
    serviceManagementReference Avancé Avancé Avancé
    signInAudience Par défaut NotSupported
    spa/redirectUris/any(p:p) Avancé Avancé
    tags/any(p:p) Par défaut Par défaut
    uniqueName Par défaut Par défaut NotSupported
    verifiedPublisher/displayName Avancé NotSupported Avancé
    web/homePageUrl Avancé NotSupported Avancé
    web/redirectUris/any(p:p) Avancé Avancé

    Les propriétés suivantes de l’entité d’application prennent en charge $count une collection dans une expression de filtre.

    Propriété eq Count 0 nombre d’eq 1
    extensionProperties/$count Avancé NotSupported
    federatedIdentityCredentials/$count Avancé NotSupported
    propriétaires/$count Avancé Avancé

    Propriétés du contrat

    Propriété eq startsWith
    customerId Par défaut
    defaultDomainName Par défaut Par défaut
    displayName Par défaut Par défaut

    Propriétés du périphérique

    Propriété eq startsWith ge/le eq Null
    accountEnabled Par défaut NotSupported
    alternativeSecurityIds/any(a:a/identityProvider) Avancé Avancé NotSupported
    alternativeSecurityIds/any(a:a/type) Par défaut Avancé NotSupported
    approximateLastSignInDateTime Par défaut Par défaut Avancé
    deviceId Par défaut NotSupported
    displayName Par défaut Par défaut Avancé
    extensionAttributes/extensionAttribute1 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute10 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute11 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute12 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute13 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute14 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute15 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute2 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute3 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute4 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute5 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute6 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute7 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute8 Avancé NotSupported Avancé
    extensionAttributes/extensionAttribute9 Avancé NotSupported Avancé
    hostnames/any(p:p) Par défaut Par défaut
    isCompliant Par défaut NotSupported
    isManaged Par défaut NotSupported
    mdmAppId Par défaut Avancé
    onPremisesLastSyncDateTime Par défaut Par défaut NotSupported
    onPremisesSecurityIdentifier Par défaut NotSupported
    onPremisesSyncEnabled Par défaut Avancé
    operatingSystem Par défaut Par défaut Avancé
    operatingSystemVersion Par défaut Par défaut Avancé
    physicalIds/any(p:p) Par défaut
    profileType Par défaut NotSupported
    registrationDateTime Avancé Avancé Avancé
    trustType Par défaut NotSupported

    Les propriétés suivantes de l’entité d’appareil prennent en charge $count une collection dans une expression de filtre.

    Propriété eq Count 0 nombre d’eq 1
    physicalIds/$count Avancé NotSupported
    systemLabels/$count Avancé NotSupported

    Propriétés du rôle d’annuaire

    Propriété eq startsWith eq Null
    description Avancé Avancé Avancé
    displayName Par défaut Avancé Avancé
    roleTemplateId Par défaut NotSupported

    Propriétés de Group

    Propriété eq startsWith ge/le eq Null
    appRoleAssignments/any(a :a/id) Par défaut
    assignedLicenses/any(a:a/skuId) Par défaut NotSupported
    classification Par défaut Par défaut NotSupported
    createdByAppId Par défaut NotSupported
    createdOnBehalfOf/id Par défaut
    description Avancé Avancé Avancé
    displayName Par défaut Par défaut Avancé
    expirationDateTime Avancé Avancé NotSupported
    hasMembersWithLicenseErrors Par défaut Par défaut
    infoCatalogs/any(p:p) Par défaut Par défaut
    isAssignableToRole Par défaut NotSupported
    mail Par défaut Par défaut Avancé
    mailEnabled Par défaut NotSupported
    mailNickname Par défaut Par défaut Avancé
    membershipRule Par défaut Par défaut NotSupported
    membershipRuleProcessingState Par défaut NotSupported
    onPremisesLastSyncDateTime Par défaut Par défaut NotSupported
    onPremisesProvisioningErrors/any(o:o/category) Par défaut NotSupported
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) Par défaut NotSupported
    onPremisesSamAccountName Avancé Avancé NotSupported
    onPremisesSecurityIdentifier Par défaut Avancé
    onPremisesSyncEnabled Par défaut Avancé
    preferredLanguage Avancé Avancé Avancé
    proxyAddresses/any(p:p) Par défaut Par défaut
    renewedDateTime Par défaut Par défaut NotSupported
    resourceBehaviorOptions/any(p:p) Par défaut
    resourceProvisioningOptions/any(p:p) Par défaut
    securityEnabled Par défaut NotSupported
    settings/any(s :s/displayName) Par défaut Par défaut NotSupported
    settings/any(s :s/id) Par défaut
    uniqueName Par défaut Par défaut NotSupported

    Les propriétés suivantes de l’entité de groupe prennent en charge $count une collection dans une expression de filtre.

    Propriété eq Count 0 nombre d’eq 1
    assignedLicenses/$count Avancé NotSupported
    onPremisesProvisioningErrors/$count Avancé NotSupported
    propriétaires/$count Avancé Avancé
    proxyAddresses/$count Avancé NotSupported

    Propriétés des contacts organisationnels

    Propriété eq startsWith ge/le eq Null
    CompanyName Avancé Avancé Avancé
    Service Par défaut Par défaut Avancé
    displayName Par défaut Par défaut Avancé
    givenName Par défaut Par défaut Avancé
    jobTitle Par défaut Par défaut Avancé
    mail Par défaut Par défaut Avancé
    mailNickname Par défaut Par défaut Avancé
    manager/id Par défaut
    onPremisesLastSyncDateTime Par défaut Par défaut NotSupported
    onPremisesProvisioningErrors/any(o:o/category) Par défaut NotSupported
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) Par défaut NotSupported
    onPremisesSyncEnabled Par défaut Avancé
    proxyAddresses/any(p:p) Par défaut Par défaut
    surname Par défaut Par défaut Avancé

    Les propriétés suivantes de l’entité orgContact prennent en charge $count une collection dans une expression de filtre.

    Propriété eq Count 0 nombre d’eq 1
    onPremisesProvisioningErrors/$count Avancé NotSupported
    proxyAddresses/$count Avancé NotSupported

    Propriétés principales du service

    Propriété eq startsWith ge/le eq Null
    accountEnabled Par défaut NotSupported
    alternativeNames/any(p:p) Par défaut Par défaut
    appId Par défaut NotSupported
    appOwnerOrganizationId Avancé NotSupported
    appRoleAssignedTo/any(a :a/id) Par défaut
    appRoleAssignmentRequired Avancé NotSupported
    appRoleAssignments/any(a :a/id) Par défaut
    applicationTemplateId Par défaut NotSupported
    createdObjects/any(c:c/id) Avancé
    delegatedPermissionClassifications/any(d :d/id) Par défaut
    description Avancé Avancé Avancé
    displayName Par défaut Par défaut Avancé
    federatedIdentityCredentials/any(f :f/issuer) Avancé Avancé NotSupported
    federatedIdentityCredentials/any(f :f/name) Avancé Avancé NotSupported
    federatedIdentityCredentials/any(f :f/subject) Avancé Avancé NotSupported
    homepage Avancé Avancé Avancé
    info/logoUrl NotSupported NotSupported Avancé
    info/termsOfServiceUrl Avancé NotSupported NotSupported
    notes Avancé Avancé Avancé
    oauth2PermissionGrants/any(o :o/id) Par défaut
    preferredSingleSignOnMode Par défaut NotSupported
    preferredTokenSigningKeyEndDateTime Par défaut Par défaut NotSupported
    publisherName Par défaut Par défaut NotSupported
    servicePrincipalNames/any(p:p) Par défaut Par défaut
    servicePrincipalType Par défaut NotSupported
    tags/any(p:p) Par défaut Par défaut
    verifiedPublisher/displayName Avancé NotSupported Avancé

    Les propriétés suivantes de la prise en charge $count de l’entité servicePrincipal d’une collection dans une expression de filtre.

    Propriété eq Count 0 nombre d’eq 1
    federatedIdentityCredentials/$count Avancé NotSupported
    ownedObjects/$count Avancé
    propriétaires/$count Avancé

    Propriétés utilisateur

    Propriété eq startsWith ge/le eq Null
    accountEnabled Par défaut NotSupported
    ageGroup Par défaut NotSupported
    appRoleAssignments/any(a :a/id) Par défaut
    assignedLicenses/any(a:a/skuId) Par défaut NotSupported
    assignedPlans/any(a:a/capabilityStatus) Avancé NotSupported
    assignedPlans/any(a:a/service) Avancé Avancé NotSupported
    assignedPlans/any(a:a/servicePlanId) Avancé NotSupported
    certificateUserIds/any(p :p) Avancé
    businessPhones/any(p:p) Avancé Avancé
    Ville Par défaut Par défaut Avancé
    cloudRealtimeCommunicationInfo/isSipEnabled Par défaut NotSupported
    CompanyName Avancé Avancé Avancé
    consentProvidedForMinor Par défaut NotSupported
    country Par défaut Par défaut Avancé
    createdDateTime Par défaut Par défaut Avancé
    createdObjects/any(c:c/id) Avancé
    creationType Par défaut NotSupported
    Service Par défaut Par défaut Avancé
    displayName Par défaut Par défaut Avancé
    employeeHireDate Avancé Avancé NotSupported
    employeeId Par défaut Avancé
    employeeOrgData/costCenter Avancé NotSupported NotSupported
    employeeOrgData/division Avancé NotSupported NotSupported
    employeeType Avancé NotSupported
    extension_4750531c75d84e8698ecd21bbd5da9f5_fruitPreference Avancé
    extension_4750531c75d84e8698ecd21bbd5da9f5_fruitPreference/any(p :p) Par défaut Par défaut
    extension_4750531c75d84e8698ecd21bbd5da9f5_test Par défaut Par défaut Avancé
    externalUserState Par défaut NotSupported
    faxNumber Avancé Avancé Avancé
    givenName Par défaut Par défaut Avancé
    identities/any(i:i/issuer) Par défaut NotSupported
    imAddresses/any(p:p) Par défaut Par défaut
    infoCatalogs/any(p:p) Par défaut Par défaut
    isLicenseReconciliationNeeded Par défaut NotSupported
    isResourceAccount Par défaut NotSupported
    jobTitle Par défaut Par défaut Avancé
    licenseDetails/any(l :l/id) Par défaut
    mail Par défaut Par défaut Avancé
    mailNickname Par défaut Par défaut Avancé
    manager/id Par défaut
    mobilePhone Avancé Avancé Avancé
    oauth2PermissionGrants/any(o :o/id) Par défaut
    officeLocation Avancé Avancé Avancé
    onPremisesExtensionAttributes/extensionAttribute1 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute10 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute11 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute12 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute13 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute14 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute15 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute2 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute3 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute4 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute5 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute6 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute7 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute8 Avancé NotSupported Avancé
    onPremisesExtensionAttributes/extensionAttribute9 Avancé NotSupported Avancé
    onPremisesImmutableId Par défaut NotSupported
    onPremisesLastSyncDateTime Par défaut Par défaut NotSupported
    onPremisesProvisioningErrors/any(o:o/category) Par défaut NotSupported
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) Par défaut NotSupported
    onPremisesSamAccountName Avancé Avancé NotSupported
    onPremisesSecurityIdentifier Par défaut Avancé
    onPremisesSipInfo/isSipEnabled Avancé NotSupported
    onPremisesSyncEnabled Par défaut Avancé
    otherMails/any(p:p) Par défaut Par défaut
    passwordPolicies NotSupported NotSupported Avancé
    passwordProfile/forceChangePasswordNextSignIn Avancé Avancé
    passwordProfile/forceChangePasswordNextSignInWithMfa Avancé Avancé
    postalCode Avancé Avancé Avancé
    preferredLanguage Avancé Avancé Avancé
    provisionedPlans/any(p:p/provisioningStatus) Avancé NotSupported
    provisionedPlans/any(p:p/service) Avancé Avancé NotSupported
    proxyAddresses/any(p:p) Par défaut Par défaut
    scopedRoleMemberOf/any(s :s/id) Par défaut
    showInAddressList Avancé NotSupported
    state Par défaut Avancé
    streetAddress Avancé Avancé Avancé
    surname Par défaut Par défaut Avancé
    usageLocation Par défaut Par défaut Avancé
    userPrincipalName Par défaut Par défaut NotSupported
    userType Par défaut Avancé

    Les propriétés suivantes de l’entité utilisateur prennent en charge $count une collection dans une expression de filtre.

    Propriété eq Count 0 nombre d’eq 1
    assignedLicenses/$count Avancé NotSupported
    onPremisesProvisioningErrors/$count Avancé NotSupported
    otherMails/$count Avancé NotSupported
    ownedObjects/$count Avancé Avancé
    proxyAddresses/$count Avancé NotSupported

    Le tableau suivant indique la prise en charge $filter par d’autres propriétés d’extension sur l’objet utilisateur .

    Type d’extension eq startsWith eq null
    Extensions de schéma Avancé Avancé Avancé
    Extensions d’ouverture NotSupported NotSupported NotSupported
    Extensions du schéma Directory Par défaut Avancé Avancé

    Prise en charge du tri par propriétés des objets Microsoft Entra ID (répertoire)

    Le tableau suivant récapitule la prise en charge $orderby par les propriétés des objets d’annuaire et indique où le tri est pris en charge via des fonctionnalités de requête avancées.

    Legend

    • Fonctionne par défaut. Ne nécessite pas de paramètres de requête avancés. L’opérateur $orderby fonctionne par défaut pour cette propriété.
    • Nécessite des paramètres de requête avancés. L’opérateur $orderbynécessite desparamètres de requête avancés, qui sont les suivants :
      • En-tête ConsistencyLevel=eventual
      • Chaîne de requête $count=true
    • L’utilisation de $filter et $orderby dans la même requête pour les objets d’annuaire nécessite toujours des paramètres de requête avancés. Pour plus d’informations, consultez Scénarios de requête qui nécessitent des fonctionnalités de requête avancées.
    Objet d’annuaire Nom de la propriété Prend en charge $orderby
    administrativeUnit createdDateTime Avancé
    administrativeUnit deletedDateTime Avancé
    administrativeUnit displayName Avancé
    application createdDateTime Avancé
    application deletedDateTime Avancé
    application displayName Avancé
    orgContact createdDateTime Avancé
    orgContact displayName Avancé
    device approximateLastSignInDateTime Avancé
    device createdDateTime Avancé
    device deletedDateTime Avancé
    device displayName Avancé
    group deletedDateTime Avancé
    group displayName Par défaut
    servicePrincipal createdDateTime Avancé
    servicePrincipal deletedDateTime Avancé
    servicePrincipal displayName Avancé
    utilisateur createdDateTime Avancé
    utilisateur deletedDateTime Avancé
    utilisateur displayName Par défaut
    utilisateur userPrincipalName Par défaut

    Traitement des erreurs pour les requêtes avancées sur des objets annuaire

    Le comptage d’objets annuaire est uniquement pris en charge en utilisant les paramètres de requêtes avancées. Si l’en-tête ConsistencyLevel=eventual n’est pas spécifié, la requête retourne une erreur lorsque le $count segment d’URL est utilisé ou ignore silencieusement le $count paramètre de requête (?$count=true) s’il est utilisé.

    GET https://graph.microsoft.com/v1.0/users/$count
    
    {
        "error": {
            "code": "Request_BadRequest",
            "message": "$count is not currently supported.",
            "innerError": {
                "date": "2021-05-18T19:03:10",
                "request-id": "d9bbd4d8-bb2d-44e6-99a1-71a9516da744",
                "client-request-id": "539da3bd-942f-25db-636b-27f6f6e8eae4"
            }
        }
    }
    

    Pour les objets d’annuaire, $search fonctionne uniquement dans les requêtes avancées. Si l’en-tête ConsistencyLevel n’est pas spécifié, la requête retourne une erreur.

    GET https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"
    
    {
        "error": {
            "code": "Request_UnsupportedQuery",
            "message": "Request with $search query parameter only works through MSGraph with a special request header: 'ConsistencyLevel: eventual'",
            "innerError": {
                "date": "2021-05-27T14:26:47",
                "request-id": "9b600954-ba11-4899-8ce9-6abad341f299",
                "client-request-id": "7964ef27-13a3-6ca4-ed7b-73c271110867"
            }
        }
    }
    

    Si une propriété ou un paramètre de requête dans l’URL est uniquement pris en charge dans les requêtes avancées, mais que l’en-tête ConsistencyLevel ou la chaîne de requête $count=true est manquant, la requête renvoie une erreur.

    GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')
    
    {
        "error": {
            "code": "Request_UnsupportedQuery",
            "message": "Operator 'endsWith' is not supported because the required parameters might be missing. Try adding $count=true query parameter and ConsistencyLevel:eventual header. Refer to https://aka.ms/graph-docs/advanced-queries for more information",
            "innerError": {
                "date": "2023-07-14T08:43:39",
                "request-id": "b3731da7-5c46-4c37-a8e5-b190124d2531",
                "client-request-id": "a1556ddf-4794-929d-0105-b753a78b4c68"
            }
        }
    }
    

    Si une propriété n’a pas été indexée pour prendre en charge un paramètre de requête, même si les paramètres de requête avancés sont spécifiés, la requête retourne une erreur.

    GET https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
    ConsistencyLevel: eventual
    
    {
        "error": {
            "code": "Request_UnsupportedQuery",
            "message": "Unsupported or invalid query filter clause specified for property 'createdDateTime' of resource 'Group'.",
            "innerError": {
                "date": "2023-07-14T08:42:44",
                "request-id": "b6a5f998-94c8-430d-846d-2eaae3031492",
                "client-request-id": "2be83e05-649e-2508-bcd9-62e666168fc8"
            }
        }
    }
    

    Toutefois, une requête qui inclut des paramètres de requête peut échouer en mode silencieux. Par exemple, pour les paramètres de requête non pris en charge et pour les combinaisons de paramètres de requête non prises en charge. Dans ce cas, examinez les données retournées par la requête pour déterminer si les paramètres de requête que vous avez spécifiés ont eu l’effet souhaité. Dans l’exemple qui suit, le paramètre @odata.count est manquant bien que la requête soit réussie.

    GET https://graph.microsoft.com/v1.0/users?$count=true
    
    HTTP/1.1 200 OK
    Content-type: application/json
    
    {
      "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
      "value":[
        {
          "displayName":"Oscar Ward",
          "mail":"oscarward@contoso.com",
          "userPrincipalName":"oscarward@contoso.com"
        }
      ]
    }