Comentarios

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

  • Artigo
  • 2 minutos de lectura

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. Anteriormente, sin esta nueva característica, era difícil crear un mecanismo confiable y eficaz para determinar los registros que se habían cambiado en Dataverse. Este artículo analiza cómo 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 la característica de seguimiento de cambios está habilitada para esa tabla. Esta característica se pueden habilitar en la interfaz de usuario (UI) de personalización o mediante programación estableciendo la propiedad ChangeTrackingEnabled como True. La anotación Org.OData.Capabilities.V1.ChangeTracking se agrega a los conjuntos de tablas que tienen habilitado el seguimiento de cambios. Para ver las anotaciones en las definiciones de la entidad, haga lo siguiente

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

Más información sobre anotaciones de metadatos en Anotaciones de metadatos.

Para obtener más información sobre el uso de la interfaz de usuario (UI) de personalización, consulte Habilitar seguimiento de cambios para controlar la sincronización de datos.

Recuperar cambios de una tabla usando API web

Los cambios realizados en las tablas pueden seguirse mediante solicitudes de la API Web, agregando odata.track-changes como encabezado preferente. El encabezado preferente odata.track-changes se usa para solicitar que se devuelva un vínculo diferencial 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 cuyos cambios se están siguiendo, por ejemplo, la solicitud que genera 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 acerca de los vínculos diferenciales 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 en los datos 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
Cache-Control: no-cache
OData-Version: 4.0
Content-Type: application/json

Respuesta

{
  "@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 vínculo diferencial devuelto en el ejemplo anterior para capturar cambios en tablas. En este ejemplo que 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

Respuesta

{
          "@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

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 odata.track-changes como encabezado de la solicitud de la API web. Un mensaje de error de tipo "El parámetro de consulta $filter/ $orderby/ $expand / $top no se admite cuando está habilitado el seguimiento de cambios está habilitado." aparece al usar estas opciones de consulta en la solicitud de la API web.

Recuperar cambios de una tabla usando un servicio de organización

Cuando el seguimiento de cambios está habilitado para una tabla, puede usar el mensaje 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 RetrieveEntityChangesRequest 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 realizará seguimiento de una tabla en recuperación de cambios. Si recuperación de cambios se ejecuta sin la versión o token, el servidor lo tratará como la versión mínima del sistema, devolviendo todos los registros como nuevos. Los objetos eliminados no se devolverán.

  • Los cambios se devolverán si el último token se encuentra dentro de un valor predeterminado de 90 días. Si es superior a 90 días, el sistema devolverá todos los registros.

  • 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 usuario final obtendrá siempre 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.

Código de ejemplo

El fragmento de código siguiente muestra cómo el mensaje de RetrieveEntityChangesRequest 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;
}

Consultar también

Definir claves alternativas para una tabla
Uso de claves alternativas
Actualizar Dynamics 365 con datos externos usando Upsert

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).