Realizar bulkUpload

  • Artículo

Espacio de nombres: microsoft.graph

Realice una nueva carga masiva mediante el trabajo de sincronización. Use este punto de conexión de API para ingerir datos en el servicio de sincronización de Microsoft Entra. El servicio de sincronización aplica las asignaciones asociadas al trabajo de sincronización y procesa los datos entrantes. El límite de velocidad de esta API es de 40 solicitudes por segundo. Cada solicitud puede contener un máximo de 50 operaciones de usuario en la matriz de operaciones de solicitud masiva.

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) SynchronizationData-User.Upload No disponible.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación SynchronizationData-User.Upload No disponible.

Nota:

Esta API está pensada principalmente para su uso dentro de una aplicación o servicio responsable de procesar datos de identidad autoritativos y cargarlos en Microsoft Entra ID. Los administradores de inquilinos pueden configurar una entidad de servicio o una identidad administrada para conceder permiso para realizar la carga. No hay ningún rol de directorio integrado Microsoft Entra asignable por el usuario independiente para esta API. Fuera de las aplicaciones que han adquirido SynchronizationData-User.Upload permiso con consentimiento de administrador, solo los usuarios administradores con el rol de administrador global pueden invocar la API.

Solicitud HTTP

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

En el punto de conexión de API, {servicePrincipalId} hace referencia al identificador de objeto de la entidad de servicio y {jobId} hace referencia al identificador del trabajo de aprovisionamiento.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Type application/scim+json. Obligatorio.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione un tipo de recurso bulkUpload . Consulte la sección de ejemplos para ver las cargas de ejemplo.

Respuesta

Si se ejecuta correctamente, devuelve una 202 Accepted respuesta y nada en el cuerpo de la respuesta. También devuelve un encabezado Location para comprobar el estado del aprovisionamiento de solicitudes masivas.

Código de estado HTTP Explicación
202 (aceptado) La solicitud masiva se almacena provisionalmente para su ejecución y la procesará el trabajo de aprovisionamiento asociado. La Location clave del encabezado de respuesta apunta al punto de conexión de registros de aprovisionamiento que se puede usar para comprobar el estado del aprovisionamiento de solicitudes masivas.
400 (solicitud incorrecta) La solicitud no se puede analizar, es sintácticamente incorrecta o infringe el esquema. La causa más común de este error es la ausencia del encabezado de solicitud Content-Type . Asegúrese de que está presente y establezca en application/scim+json.
401 (no autorizado) El encabezado de autorización no es válido o falta. Asegúrese de que el encabezado de autorización tiene un token de acceso válido.
403 (Prohibido) La operación no se permite en función del encabezado de autorización proporcionado. Asegúrese de que el cliente de API tiene el SynchronizationData-User.Upload permiso y, para escenarios delegados, el autor de la llamada debe ser un administrador global.

Ejemplos

Ejemplo 1: Carga masiva mediante el esquema de usuario y usuario empresarial de SCIM Core

Solicitud

La siguiente solicitud masiva usa el esquema estándar de usuario principal y usuario empresarial de SCIM. Tiene dos operaciones de usuario en la matriz Operations . Puede enviar un máximo de 50 operaciones de usuario en cada solicitud masiva.

Detalles de procesamiento: El servicio de aprovisionamiento lee los dos registros de usuario. Usa el atributo coincidente para userName y externalId que está configurado en la asignación de atributos del trabajo de aprovisionamiento para determinar si se va a crear, actualizar, habilitar o deshabilitar la cuenta de usuario en el directorio. Resuelve la referencia del administrador mediante el manager.value campo . Especifique el externalId del administrador del usuario en este campo. En el ejemplo siguiente, el servicio de aprovisionamiento asigna a Barbara Jensen como administrador 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
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{}

Ejemplo 2: Carga masiva mediante el espacio de nombres de esquema personalizado SCIM

Solicitud

La siguiente solicitud masiva usa el esquema estándar de usuario principal y usuario empresarial de SCIM. Tiene otro espacio de nombres de esquema personalizado llamado urn:contoso:employee con dos atributos HireDate y JobCode. La schemas matriz del objeto de datos se actualiza para incluir el espacio de nombres de esquema personalizado.

Detalles de procesamiento: El servicio de aprovisionamiento lee los dos registros de usuario. Usa el atributo coincidente para userName y externalId que está configurado en la asignación de atributos del trabajo de aprovisionamiento para determinar si se va a crear, actualizar, habilitar o deshabilitar la cuenta de usuario en el directorio. Si incluye los dos atributos personalizados y urn:contoso:employee:JobCode en la asignación de atributos urn:contoso:employee:HireDate de trabajo de aprovisionamiento, se procesa y se establecen los atributos de destino correspondientes.

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
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{}

Ejemplo 3: Carga masiva para actualizar un usuario existente

Solicitud

En la siguiente solicitud masiva se muestra cómo actualizar los atributos de un usuario Microsoft Entra existente, cambiar el departamento del usuario y deshabilitar el inicio de sesión para el usuario. En este ejemplo se supone que ha configurado una asignación para los campos externalId, department y active, y que tiene un usuario Microsoft Entra existente que tiene un atributo que coincide con 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
}

Respuesta

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{}