Effectuer un chargement en bloc

  • Article

Espace de noms: microsoft.graph

Effectuez un nouveau chargement en bloc à l’aide du travail de synchronisation. Utilisez ce point de terminaison d’API pour ingérer des données dans le service de synchronisation Microsoft Entra. Le service de synchronisation applique les mappages associés au travail de synchronisation et traite les données entrantes. La limite de débit pour cette API est de 40 requêtes par seconde. Chaque requête peut contenir un maximum de 50 opérations utilisateur dans le tableau Opérations de requête en bloc.

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) SynchronizationData-User.Upload Non disponible.
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application SynchronizationData-User.Upload Non disponible.

Remarque

Cette API est principalement destinée à être utilisée au sein d’une application ou d’un service chargé de traiter les données d’identité faisant autorité et de les charger dans Microsoft Entra ID. Les administrateurs de locataire peuvent configurer un principal de service ou une identité managée pour accorder l’autorisation d’effectuer le chargement. Il n’existe aucun rôle d’annuaire intégré Microsoft Entra assignable par l’utilisateur distinct pour cette API. En dehors des applications qui ont acquis SynchronizationData-User.Upload l’autorisation avec le consentement de l’administrateur, seuls les utilisateurs administrateurs disposant du rôle Administrateur général peuvent appeler l’API.

Requête HTTP

POST /servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

Dans le point de terminaison d’API, {servicePrincipalId} fait référence à l’ID d’objet du principal de service et {jobId} à l’ID du travail d’approvisionnement.

En-têtes de demande

Nom Description
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Content-Type application/scim+json. Obligatoire.

Corps de la demande

Dans le corps de la demande, fournissez un type de ressource bulkUpload . Reportez-vous à la section exemples pour obtenir des exemples de charges utiles.

Réponse

En cas de réussite, retourne une 202 Accepted réponse et rien dans le corps de la réponse. Elle retourne également un en-tête Location pour vérifier la status de l’approvisionnement des demandes en bloc.

Code d’état HTTP Explication
202 (Accepté) La demande en bloc est intermédiaire pour l’exécution et sera traitée par le travail d’approvisionnement associé. La Location clé dans l’en-tête de réponse pointe vers le point de terminaison des journaux d’approvisionnement qui peut être utilisé pour case activée la status de l’approvisionnement des demandes en bloc.
400 (requête incorrecte) La requête est irmédiable, syntaxiquement incorrecte ou viole le schéma. La cause la plus courante de cette erreur est l’absence de l’en-tête de requête Content-Type . Assurez-vous qu’il est présent et défini sur application/scim+json.
401 (non autorisé) L’en-tête d’autorisation n’est pas valide ou est manquant. Vérifiez que l’en-tête d’autorisation a un jeton d’accès valide.
403 (Interdit) L’opération n’est pas autorisée en fonction de l’en-tête d’autorisation fourni. Assurez-vous que le client d’API dispose de l’autorisation SynchronizationData-User.Upload et, pour les scénarios délégués, l’appelant doit être un administrateur général.

Exemples

Exemple 1 : chargement en bloc à l’aide du schéma utilisateur SCIM Core et Enterprise User

Demande

La requête en bloc suivante utilise le schéma utilisateur principal standard SCIM et utilisateur d’entreprise. Il comporte deux opérations utilisateur dans le tableau Opérations . Vous pouvez envoyer un maximum de 50 opérations utilisateur dans chaque requête en bloc.

Détails du traitement : Le service d’approvisionnement lit les deux enregistrements utilisateur. Il utilise l’attribut correspondant pour userName et externalId qui est configuré dans le mappage d’attributs du travail d’approvisionnement pour déterminer s’il faut créer, mettre à jour, activer ou désactiver le compte d’utilisateur dans l’annuaire. Il résout la référence du gestionnaire à l’aide du manager.value champ . Spécifiez le externalId du responsable de l’utilisateur dans ce champ. Dans l’exemple suivant, le service d’approvisionnement affecte Barbara Jensen en tant que responsable de Kathy Jensen.

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            }
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
              }
            }
        }
    }
],
    "failOnErrors": null
}

Réponse

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd10f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

Exemple 2 : chargement en bloc à l’aide de l’espace de noms de schéma personnalisé SCIM

Demande

La requête en bloc suivante utilise le schéma utilisateur principal standard SCIM et utilisateur d’entreprise. Il a un autre espace de noms de schéma personnalisé appelé urn:contoso:employee avec deux attributs HireDate et JobCode. Le schemas tableau dans l’objet de données est mis à jour pour inclure l’espace de noms de schéma personnalisé.

Détails du traitement : Le service d’approvisionnement lit les deux enregistrements utilisateur. Il utilise l’attribut correspondant pour userName et externalId qui est configuré dans le mappage d’attributs du travail d’approvisionnement pour déterminer s’il faut créer, mettre à jour, activer ou désactiver le compte d’utilisateur dans l’annuaire. Si vous incluez les deux attributs personnalisés et urn:contoso:employee:JobCode dans votre mappage d’attributs urn:contoso:employee:HireDate de travail d’approvisionnement, ils sont traités et les attributs cibles correspondants sont définis.

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:contoso:employee"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            },
            "urn:contoso:employee": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "AB-1002"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:contoso:employee"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:contoso:employee": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "AB-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

Réponse

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd10f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beeb9ea0-f7e4-4fe7-8507-cd834c88f18b

{}

Exemple 3 : chargement en bloc pour la mise à jour d’un utilisateur existant

Demande

La requête en bloc suivante montre comment mettre à jour les attributs d’un utilisateur Microsoft Entra existant, modifier le service de l’utilisateur et désactiver la connexion pour l’utilisateur. Cet exemple suppose que vous avez configuré un mappage pour les champs externalId, department et active, et que vous disposez d’un utilisateur Microsoft Entra qui a un attribut correspondant à externalId.

POST https://graph.microsoft.com/v1.0/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload
Authorization: Bearer <token>
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
        {
            "method": "POST",
            "bulkId": "7172023",
            "path": "/Users",
            "data": {
                "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
                "externalId": "7172023",
                "active": false,
                "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                    "department": "Tour Ops"
                }
            }
        }
    ],
    "failOnErrors": null
}

Réponse

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 202 Accepted
Content-Type: application/scim+json
client-request-id: 92cd20f6-fcc3-5d61-098e-a6dd35e460ef
content-length: "0"
location: "https://graph.microsoft.com/beta/auditLogs/provisioning/?$filter=jobid%20eq%20'API2AAD.b16687d38faf42adb29892cdcaf01c6e.1a03de52-b9c3-4e2c-a1e3-9145aaa8e530'"
request-id: beec9ea0-f7e4-4fe7-8507-cd834c88f18b

{}