Uso del seguimiento de cambios para sincronizar los datos con sistemas externos

  • Artículo

La característica de seguimiento de Microsoft Dataverse proporciona una forma de mantener los datos sincronizados de forma eficiente detectando qué datos se han modificado desde que los datos se extrajeron inicialmente o se sincronizaron por última vez. Este artículo analiza cómo habilitar y recuperar los cambios de una tabla.

Habilitar seguimiento de cambios para una tabla

Antes de recuperar los cambios para una tabla, asegúrese de que el seguimiento de cambios está habilitado para esa tabla.

Puede verificar si esta característica está habilitada o habilitarla usando Power Apps. Seleccione Datos > Tablas y la tabla específica. Bajo Opciones avanzadas, encontrará la propiedad Seguir cambios.

Puede configurar esto programáticamente configurando la Propiedad EntityMetadata.ChangeTrackingEnabled como True.

Nota

Una vez que se ha habilitado el seguimiento de cambios para una tabla, no es posible deshabilitarlo.

Para obtener más información sobre cómo usar Power Apps: Crear y editar tablas mediante Power Apps

Hay dos formas de verificar si el seguimiento de cambios está habilitado para una tabla usando la API web de Dataverse.

  1. Puede consultar EntityDefinitions con la siguiente solicitud GET:

    GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName&$filter=ChangeTrackingEnabled eq true

    Hay tablas del sistema con el seguimiento de cambios habilitado, por ejemplo Auditoría (Auditoría). Puede usar la siguiente consulta para ver la lista completa:

    GET [Organization URI]/api/data/v9.2/EntityDefinitions?$filter=ChangeTrackingEnabled eq true and IsCustomEntity eq false&$select=LogicalName

    Más información: Consultar definiciones de tabla mediante la API web

  2. Encuentre esta información en el documento del servicio de $metadatos de la API web. La anotación Org.OData.Capabilities.V1.ChangeTracking se configura para los conjuntos de entidades que tienen habilitado el seguimiento de cambios.

    Para ver las anotaciones en el documento de servicio API web CDSL, use esta consulta de API web:

    GET [Organization URI]/api/data/v9.2/$metadata?annotations=true

    Los conjuntos de entidades que representan tablas en las que está habilitado el seguimiento de cambios tienen esta anotación:

    <Annotation Term="Org.OData.Capabilities.V1.ChangeTracking">
   <Record>
         <PropertyValue Property="Supported" Bool="true" />
   </Record>
</Annotation>

    Más información: Anotaciones de metadatos.

Tablas no aptas para Change Tracking

Algunas tablas no se pueden habilitar para el seguimiento de cambios. Puede comprobar si una tabla es apta para el Change Tracking si comprueba el valor de la propiedad administrada EntityMetadata.CanChangeTrackingBeEnabled. Para ver qué tablas no se pueden habilitar para el seguimiento de cambios, use esta consulta de API web:

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=SchemaName,ChangeTrackingEnabled&$filter=ChangeTrackingEnabled eq false and CanChangeTrackingBeEnabled/Value eq false

Más información:

Recuperar cambios de una tabla usando API web

Los cambios realizados en las tablas pueden seguirse mediante solicitudes de la API Web agregando el encabezado Prefer: odata.track-changes. Este encabezado solicita que se devuelva un delta link que pueda usarse después para recuperar los cambios de la tabla.

Los vínculos diferenciales son vínculos opacos generados por servicios que el cliente utiliza para recuperar los cambios posteriores a un resultado. Se basan en una consulta de definición que describe el conjunto de resultados para los que se realiza un seguimiento de los cambios. Por ejemplo, la solicitud que generó los resultados que contienen el vínculo diferencial. El vínculo diferencial codifica el conjunto de tablas cuyos se están siguiendo, junto con un punto de partida desde el que desea realizar un seguimiento de los cambios. Más información: Oasis OData Versión 4.0 - Vínculos diferenciales

Ejemplo de recuperación de cambios en tablas usando la API Web

En este ejemplo se muestra cómo recuperar los cambios realizados para la tabla de cuentas mediante la API web.

Solicitud:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax HTTP/1.1
Prefer: odata.track-changes
OData-Version: 4.0
Content-Type: application/json

Respuesta:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.track-changes

{
  "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts(name,accountnumber,telephone1,fax)",
"@odata.deltaLink": "[Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44",
"value":[
           {
              "@odata.etag":"W/\"915244\"",
              "name":"Monte Orton",
              "accountnumber":null,
              "telephone1":"555000",
              "fax":"10101",
              "accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
           }
       ]
}

Puede usar el Uri @odata.deltaLink devuelto en el ejemplo anterior para capturar cambios en tablas. En este ejemplo, se ha creado una cuenta y se ha eliminado una cuenta existente. El vínculo diferencial devuelto desde la solicitud anterior recopila estos cambios, tal como se muestra en el ejemplo siguiente.

Solicitud:

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber,telephone1,fax&$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
OData-Version: 4.0
Content-Type: application/json

Respuesta:

HTTP/1.1 200 OK
OData-Version: 4.0

{
          "@odata.context":"[Organization URI]/data/v9.0/$metadata#accounts(name,telephone1,fax)/$delta",
          "@odata.deltaLink":"[Organization URI]/api/data/v9.0/accounts?$select=name,telephone1,fax&$deltatoken=919058%2108%2f22%2f2017%2008%3a21%3a20",
"value":
    [
        {
            "@odata.etag":"W/\"915244\"",
            "name":"Monte Orton",
            "telephone1":"555000",
            "fax":"10101",
            "accountid":"60c4e274-0d87-e711-80e5-00155db19e6d"
        },
        {
            "@odata.context":"[Organization URI]/api/data/v9.0/$metadata#accounts/$deletedEntity",
            "id":"2e451703-c686-e711-80e5-00155db19e6d",
            "reason":"deleted"
        }
    ]
}

La respuesta para el vínculo diferencial devuelto en la solicitud de seguimiento de cambio inicial contiene otro vínculo diferencial. Este vínculo diferencial ayuda a recuperar todos los cambios posteriores de tablas. Si no hay cambios de tabla realizados después de la solicitud de seguimiento de cambio inicial invocada, se recibe una respuesta JSON vacía.

Recuperar el número de cambios efectuados en tablas usando la API Web

$count puede agregarse al vínculo diferencial devuelto en la primera solicitud de cambio inicial, como se muestra en el ejemplo siguiente, para obtener el número de los cambios efectuados.

Solicitud:

GET [Organization URI]/api/data/v9.0/accounts/$count?$deltatoken=919042%2108%2f22%2f2017%2008%3a10%3a44
OData-Version: 4.0
Content-Type: application/json

Opciones de la consulta no admitidas en la solicitud de la API Web de seguimiento de cambios

Las opciones de consulta del sistema $filter, $orderby, $expand y $top no se admiten cuando se utiliza el encabezado Prefer: odata.track-changes en una solicitud de la API web. El mensaje de error The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled. se devuelve al usar estas opciones de consulta en la solicitud de la API web.

Recuperar cambios de una tabla usando .NET SDK

Cuando el seguimiento de cambios está habilitado para una tabla, puede usar el mensaje RetrieveEntityChanges con la clase RetrieveEntityChangesRequest para recuperar los cambios para esa tabla.

La primera vez que se usa este mensaje devuelve todos los registros de la tabla y que los datos se pueden usar para rellenar el almacenamiento externo. El mensaje también devuelve un número de versión que se enviará con el uso siguiente del mensaje RetrieveEntityChanges de modo que solo se devolverán los datos de los cambios que se han producido desde esa versión.

Debe conocer las siguientes restricciones para recuperar los cambios de una tabla:

  • Solo se realiza el seguimiento de una tabla en recuperación de cambios. Si RetrieveEntityChanges se ejecuta sin la versión o token, el servidor lo trata como la versión mínima del sistema, devolviendo todos los registros como nuevos. Los objetos eliminados no se devuelven.
  • Los cambios se devuelven si el último token se encuentra dentro de un valor predeterminado de 7 días. Esta duración está controlada por el valor de la columna ExpireChangeTrackingInDays de la tabla de organización y se puede cambiar. Si hay cambios sin procesar anteriores al valor configurado, el sistema lanza una excepción.
  • Si un cliente tiene un conjunto de cambios para una tabla, supongamos la versión 1, un registro se crea y elimina antes de la siguiente consulta cambios, este obtendrá el elemento eliminado incluso aunque no tuviera el elemento para empezar.
  • Los registros se recuperan en el orden determinado por la lógica del lado del servidor. Normalmente, el llamador obtendrá todos los registros nuevos o actualizados primero (clasificados por número de versión) seguidos de los registros eliminados. Si hay 3000 registros creados o actualizados y 2000 registros eliminados, Dataverse devuelve una colección de 5000 registros, que tienen las primeras 3000 entradas formadas por registros nuevos o actualizados y las 2000 últimas entradas de registros eliminados.
  • Si la colección de registros nuevos o actualizados es superior a 5000, el usuario puede desplazarse entre las páginas de la colección.
  • El usuario que llama debe tener acceso de lectura en el nivel de organización a la tabla. Si el usuario tiene acceso de lectura limitado, el sistema arroja un error de verificación de privilegios.

Código de muestra .NET SDK

El fragmento de código siguiente muestra cómo el mensaje de RetrieveEntityChanges se usa para recuperar los cambios de una tabla. Para ver el ejemplo completo, vea Sincronizar datos con sistemas externos utilizando seguimiento de cambios.

string token;

// Initialize page number.
int pageNumber = 1;
List<Entity> initialrecords = new List<Entity>();

// Retrieve records by using Change Tracking feature.
RetrieveEntityChangesRequest request = new RetrieveEntityChangesRequest();
request.EntityName = _customBooksEntityName.ToLower();
request.Columns = new ColumnSet("sample_bookcode", "sample_name", "sample_author");
request.PageInfo = new PagingInfo() { Count = 5000, PageNumber = 1, ReturnTotalRecordCount = false };


// Initial Synchronization. Retrieves all records as well as token value.
Console.WriteLine("Initial synchronization....retrieving all records.");
while (true)
{
    RetrieveEntityChangesResponse response = (RetrieveEntityChangesResponse)_serviceProxy.Execute(request);

    initialrecords.AddRange(response.EntityChanges.Changes.Select(x => (x as NewOrUpdatedItem).NewOrUpdatedEntity).ToArray());
    initialrecords.ForEach(x => Console.WriteLine("initial record id:{0}", x.Id));
    if (!response.EntityChanges.MoreRecords)
    {
        // Store token for later query
        token = response.EntityChanges.DataToken;
        break;

    }
    // Increment the page number to retrieve the next page.
    request.PageInfo.PageNumber++;
    // Set the paging cookie to the paging cookie returned from current results.
    request.PageInfo.PagingCookie = response.EntityChanges.PagingCookie;
}

Consulte también

Definir claves alternativas para una tabla
Usar una clave alternativa para hacer referencia a un registro
Actualizar Dynamics 365 con datos externos usando Upsert
Consultar definiciones de tabla con la API web

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).