Introducción a la API de sincronización de Azure AD

Espacio de nombres: microsoft.graph

Importante

Las API de la /beta versión 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 versiones .

La sincronización de identidades de Azure Active Directory (Azure AD) (también denominada "aprovisionamiento") le permite automatizar el aprovisionamiento (creación, mantenimiento) y la eliminación (eliminación) de identidades de cualquiera de las siguientes opciones:

  • Active Directory a Azure AD
  • Día laborable a Azure AD
  • Aplicaciones de Azure AD a la nube como Dropbox, Salesforce, ServiceNow y mucho más

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 acerca de la sincronización en Azure AD, vea:

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

Trabajo de sincronización

Los trabajos de sincronización realizan la sincronización ejecutándose periódicamente en segundo plano, sondando los cambios en un directorio e inyéndolos a otro directorio. El trabajo de sincronización siempre es específico de una instancia determinada de una aplicación en el espacio empresarial. Como parte de la configuración del trabajo de sincronización, debe dar 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 el 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 cumplan una condición determinada.

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, vea el esquema de sincronización.

Plantilla de sincronización

La plantilla de sincronización proporciona opciones de sincronización preconfiguradas para una aplicación determinada. Esta configuración (lo más importante, el esquema desincronizació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, vea la 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. Los ejemplos siguientes muestran cómo trabajar con los recursos synchronizationJob y synchronizationSchema.

Authorization

La API de sincronización de Azure AD usa OAuth 2.0 para la autorización. Antes de realizar solicitudes a la API, debe obtener un token de acceso. Para obtener más información, vea Obtener tokens de acceso para llamar a Microsoft Graph. Para obtener acceso a los recursos de sincronización, la aplicación necesita permisos Directory.ReadWrite.All. Para obtener más información, vea Permisos de directorio.

Buscar el objeto de entidad de seguridad de servicio por nombre para mostrar

En el ejemplo siguiente se muestra cómo buscar el objeto principal 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"
      }
   ]
}

Buscar el objeto de entidad de servicio por identificador de aplicación

En el siguiente ejemplo 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"
        }
    ]
}

Enumerar 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": {}
        }
    ]
}

Obtener el 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": {}
}

Obtener el esquema de sincronización

En el siguiente ejemplo 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": []
}

Consulta también