Compartir a través de

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

La característica de seguimiento de cambios de Microsoft Dataverse proporciona una manera de mantener los datos sincronizados de forma eficaz mediante la detección de los datos que han cambiado 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 de 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. En Opciones avanzadas, encontrará la propiedad Seguimiento de cambios .

Establezca esta propiedad mediante programación estableciendo la propiedad EntityMetadata.ChangeTrackingEnabled en .True

Nota

Después de habilitar el seguimiento de cambios para una tabla, no se puede deshabilitar.

Para obtener más información sobre cómo usar Power Apps, consulte Creación y edición de tablas mediante Power Apps.

Para comprobar si el seguimiento de cambios está habilitado para una tabla mediante la API web de Dataverse, use uno de los métodos siguientes:

  1. Consulte EntityDefinitions mediante la solicitud siguiente GET :

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

    Algunas tablas del sistema tienen habilitado el seguimiento de cambios, como Auditoría (Audit). Para ver la lista completa, use la consulta siguiente:

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

    Para obtener más información, consulte Query table definitions using the Web API (Consultar definiciones de tabla mediante la API web).

  2. Consulte el documento de servicio de la API web $metadata. 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>

    Para obtener más información, vea Anotaciones de metadatos.

Tablas no elegibles para seguimiento de cambios

No se puede habilitar el seguimiento de cambios para algunas tablas. Para comprobar si una tabla es apta para el seguimiento de cambios, compruebe 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

Puede realizar un seguimiento de los cambios realizados en tablas mediante solicitudes de API web que incluyan el Prefer: odata.track-changes encabezado . Este encabezado solicita que se devuelva un vínculo delta , que puede usar posteriormente para recuperar los cambios de 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 cuyas cambios se están siguiendo, además de un punto de inicio desde el que se realizan un seguimiento de los cambios. Para obtener más información, consulte Oasis OData Versión 4.0 - Vínculos delta.

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"
           }
       ]
}

Use el @odata.deltaLink URI devuelto del ejemplo anterior para capturar los cambios en las tablas. En este ejemplo, ha creado una nueva cuenta y ha eliminado una cuenta existente. El vínculo delta devuelto de la solicitud anterior captura estos cambios, 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 delta link ayuda a recuperar todos los cambios posteriores en las tablas. Si no se produce ningún cambio de tabla después de la solicitud inicial de seguimiento de cambios, la respuesta contiene JSON vacío.

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

Para obtener el número de cambios, agregue $count al vínculo delta devuelto desde la solicitud inicial de seguimiento de cambios, como se muestra en el ejemplo siguiente.

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 $filterde consulta del sistema , $orderby, $expandy $top no se admiten cuando se usa el Prefer: odata.track-changes encabezado en una solicitud de API web. Si usa estas opciones de consulta en la solicitud de API web, recibirá un mensaje de error: The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled..

Recuperar cambios de una tabla usando .NET SDK

Al habilitar el seguimiento de cambios para una tabla, use el RetrieveEntityChanges mensaje con la clase RetrieveEntityChangesRequest para recuperar los cambios de esa tabla.

La primera vez que use este mensaje, devuelve todos los registros de la tabla. Puede usar esos datos para rellenar el almacenamiento externo. El mensaje también devuelve un número de versión que se envía con el siguiente uso del RetrieveEntityChanges mensaje para que solo se devuelvan los datos de los cambios que se produjeron desde esa versión.

Tenga en cuenta las restricciones siguientes al recuperar los cambios de una tabla:

  • Solo puede realizar un seguimiento de una tabla en la recuperación de cambios. Si se ejecuta RetrieveEntityChanges sin versión o token, el servidor lo trata como la versión mínima del sistema y devuelve todos los registros como nuevos. No se devuelven objetos eliminados.
  • Los cambios se devuelven si el último token está dentro de un valor predeterminado de siete días. El valor de la columna ExpireChangeTrackingInDays de la tabla Organization controla esta duración y se puede cambiar. Si los cambios sin procesar son anteriores al valor configurado, el sistema produce una excepción.
  • Si un cliente tiene un conjunto de cambios para una tabla, por ejemplo, la versión 1, y se crea y elimina un registro antes de la siguiente consulta de cambios, el cliente obtendrá el elemento eliminado aunque inicialmente no tuviera el elemento.
  • Los registros se recuperan en el orden determinado por la lógica del lado del servidor. Normalmente, el autor de la llamada obtiene primero todos los registros nuevos o actualizados (ordenados por número de versión) seguidos de registros eliminados. Si hay 3000 registros creados o actualizados y 2000 registros eliminados, Dataverse devuelve una colección de 5000 registros para tablas estándar, que tienen las 3000 primeras entradas compuestas por registros nuevos o actualizados y las 2000 últimas entradas por registros eliminados.
  • Si la colección de elementos nuevos o actualizados es superior a 5,000, el usuario puede desplazarse entre las páginas de la colección.
  • El usuario que llama debe tener acceso de lectura a nivel organizacional a la tabla. Si el usuario tiene acceso de lectura limitado, el sistema arroja un error de verificación de privilegios.

Código de ejemplo del SDK de .NET

El siguiente fragmento de código muestra cómo usar el RetrieveEntityChanges mensaje 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

  • Last updated on