Realizar BulkUpload

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Realiza un nuevo BulkUpload mediante el trabajo de sincronización. Utilice este punto de conexión de API para incorporar datos en el servicio de sincronización de Microsoft Entra. El servicio de sincronización aplica las asignaciones asociadas con el 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.

Nota:

Esta API está en versión preliminar pública y solo está disponible para su uso con aplicaciones de aprovisionamiento entrante controladas por API.

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos 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.OwnedBy SynchronizationData-User.Upload

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 de Microsoft Entra asignable por el usuario independiente para esta API. Además de las aplicaciones que han adquirido SynchronizationData-User.Upload permisos con el consentimiento del administrador, los usuarios administradores con el rol de administrador de usuarios pueden invocar la API.

Solicitud HTTP

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

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

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre autenticación y 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 cargas útiles de ejemplo.

Respuesta

Si tiene éxito, devuelve una 202 Accepted respuesta y nada en el cuerpo de la respuesta. También devuelve un encabezado de ubicación para comprobar el estado del aprovisionamiento de solicitudes en masa.

Código de estado HTTP Explicación
202 (Aceptado) La solicitud masiva se almacena provisionalmente para su ejecución y es procesada por el trabajo de aprovisionamiento asociado. La Location clave en el encabezado de respuesta apunta al punto de conexión de registros de aprovisionamiento que se puede usar para verificar 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 Content-Typede solicitud. Asegúrese de que esté presente y configurado 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 tenga 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 tenga los SynchronizationData-User.Upload permisos y, para escenarios delegados, la persona que llama debe ser un administrador de usuarios.

Ejemplos

Ejemplo 1: Carga masiva mediante el esquema de usuario principal SCIM y usuario de empresa

Solicitud

La siguiente solicitud masiva usa el esquema de usuario principal y usuario empresarial estándar 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 del procesamiento: El servicio de aprovisionamiento lee los dos registros de usuario. Utiliza el atributo coincidente for userName y externalId que se configura en la asignación de atributos del trabajo de aprovisionamiento para determinar si se debe crear, actualizar, habilitar o deshabilitar la cuenta de usuario en el directorio. Resuelve la referencia de 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 administradora de Kathy Jensen.

POST https://graph.microsoft.com/beta/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 de usuario principal y usuario empresarial estándar 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 del esquema personalizado.

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

POST https://graph.microsoft.com/beta/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 en bloque para actualizar un usuario existente

Solicitud

La siguiente solicitud masiva muestra cómo actualizar los atributos de un usuario existente de Microsoft Entra, 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 de Microsoft Entra existente que tiene un atributo que coincide con externalId.

POST https://graph.microsoft.com/beta/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

{}
  • Last updated on