Introducción a la API de sincronización de Microsoft Entra

  • Artículo

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.

Microsoft Entra sincronización de identidades (también denominada "aprovisionamiento") permite automatizar el aprovisionamiento (creación, mantenimiento) y desaprovisionamiento (eliminación) de identidades de cualquiera de las siguientes opciones:

  • Active Directory para Microsoft Entra ID
  • Workday para Microsoft Entra ID
  • Microsoft Entra ID a aplicaciones en la nube como Dropbox, Salesforce, ServiceNow, etc.

Puede usar las API de sincronización en Microsoft Graph para administrar la sincronización de identidad mediante programación, incluyendo:

  • Crear, iniciar y detener trabajos de sincronización
  • Realizar cambios en el esquema de sincronización de las tareas
  • Comprobar el estado de la sincronización actual

Para obtener más información sobre la sincronización en Microsoft Entra ID, consulte:

También puede probar la API en el Explorador de Graph en un inquilino de ejemplo o en su propio inquilino.

Trabajo de sincronización

Los trabajos de sincronización realizan la sincronización ejecutándose periódicamente en segundo plano, sondeando los cambios en un directorio y insertándolos en otro directorio. El trabajo de sincronización siempre es específico de una instancia determinada de una aplicación en el inquilino. Como parte de la configuración del trabajo de sincronización, debe conceder autorización para leer y escribir objetos en el directorio de destino y personalizar el esquema de sincronización del trabajo.

Para obtener más información, vea Trabajo de sincronización.

Esquema de sincronización

El esquema de sincronización define qué objetos se sincronizarán y cómo se sincronizarán. El esquema de sincronización contiene la mayor parte de la información de configuración de un trabajo de sincronización determinado. Normalmente, personalizará algunas de las asignaciones de atributos o agregará un filtro de ámbito para sincronizar solo los objetos que cumplen una determinada condición.

El esquema de sincronización incluye los siguientes componentes:

  • Definiciones de directorio
  • Reglas de sincronización
  • Asignaciones de objetos

Para obtener más información, consulte esquema de sincronización.

Plantilla de sincronización

La plantilla de sincronización proporciona la configuración de sincronización preconfigurada para una aplicación determinada. Esta configuración (lo más importante, el esquema de sincronización) se usará de forma predeterminada para cualquier trabajo de sincronización basado en la plantilla. El desarrollador de la aplicación especifica las plantillas.

Para obtener más información, consulte plantilla de sincronización.

Trabajar con la API de sincronización

Trabajar con la API de sincronización implica principalmente el acceso a los recursos synchronizationJob y synchronizationSchema . Para buscar el recurso synchronizationJob , debe conocer el identificador del objeto de entidad de servicio al que pertenece el trabajo de sincronización. En los ejemplos siguientes se muestra cómo trabajar con los recursos synchronizationJob y synchronizationSchema .

Autorización

Para trabajar con las API de sincronización de Microsoft Entra, Microsoft Graph admite los siguientes permisos granulares:

  • Synchronization.Read.All
  • Synchronization.ReadWrite.All
  • Application.ReadWrite.OwnedBy
  • Application.Read.All
  • Application.ReadWrite.All

Y los siguientes roles de directorio de Microsoft Entra:

  • Administrador de la aplicación
  • Administrador de aplicaciones en la nube
  • Administrador de identidades híbridas
  • Administrador global

Para obtener más información sobre los privilegios que necesita para llamar a cada API, visite la documentación de referencia de API correspondiente.

Búsqueda del objeto de entidad de servicio por nombre para mostrar

En el ejemplo siguiente se muestra cómo buscar el objeto de entidad de servicio por nombre para mostrar.

Solicitud

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')

Respuesta

HTTP/1.1 200 OK

{
   "value":[
      {
         "id":"bc0dc311-87df-48ac-91b1-259bd2c3a31c",
         "appId":"f7808c5e-cb57-4e37-8094-406d302c0f8d",
         "displayName":"Salesforce"
      },
      {
         "id":"d813d7d7-0f41-4edc-b284-d0dfaf399d15",
         "appId":"219561ee-1480-4c67-9aa6-63d861fae3ef",
         "displayName":"salesforce 3"
      }
   ]
}

Búsqueda del objeto de entidad de servicio por identificador de aplicación

En el ejemplo siguiente se muestra cómo buscar el objeto de entidad de servicio por identificador de aplicación.

Solicitud

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=AppId eq '219561ee-1480-4c67-9aa6-63d861fae3ef'

Respuesta

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "d813d7d7-0f41-4edc-b284-d0dfaf399d15",
            "appId": "219561ee-1480-4c67-9aa6-63d861fae3ef",
            "displayName": "salesforce 3"
        }
    ]
}

Enumeración de trabajos de sincronización existentes

En el ejemplo siguiente se muestra cómo enumerar los trabajos de sincronización existentes.

Solicitud

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs
GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs

Respuesta

HTTP/1.1 200 OK

{
    "value": [
        {
            "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
            "templateId": "SfSandboxOutDelta",
            "schedule": {
                "expiration": null,
                "interval": "PT20M",
                "state": "Active"
            },
            "status": {}
        }
    ]
}

Obtención del estado del trabajo de sincronización

En el ejemplo siguiente se muestra cómo obtener el estado de un trabajo de sincronización.

Solicitud

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}

GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs/SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa

Respuesta

HTTP/1.1 200 OK

{
    "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
    "templateId": "SfSandboxOutDelta",
    "schedule": {
        "expiration": null,
        "interval": "PT20M",
        "state": "Active"
    },
    "status": {}
}

Obtención del esquema de sincronización

En el ejemplo siguiente se muestra cómo obtener el esquema de sincronización.

Solicitud

GET https://graph.microsoft.com/beta/servicePrincipals/{id}/synchronization/jobs/{jobId}/schema

Respuesta

HTTP/1.1 200 OK

{
    "directories": [],
    "synchronizationRules": []
}

Contenido relacionado