Freigeben über

Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung

  • Artikel

Mit der neuen Änderungsnachverfolgungsfunktion in Microsoft Dataverse können die Daten effizient synchronisiert werden, indem festgestellt wird, welche Daten geändert wurden, nachdem die Daten ursprünglich extrahiert oder zuletzt synchronisiert wurden. Dieser Artikel beschreibt, wie Sie Änderungen für eine Tabelle aktivieren und abrufen können.

Aktivieren der Änderungsverfolgung für eine Tabelle

Bevor Sie die Änderungen für eine Tabelle abrufen, stellen Sie sicher, dass die Änderungsverfolgung für diese Tabelle aktiviert ist.

Sie können überprüfen, ob diese Funktion aktiviert ist, oder sie aktivieren, indem Sie Power Apps verwenden. Wählen Sie Daten > Tabellen und die spezifische Tabelle aus. Unter Erweiterte Optionen finden Sie die Eigenschaft Änderungen nachverfolgen.

Sie können dies programmgesteuert festlegen, indem Sie die EntityMetadata.ChangeTrackingEnabled-Eigenschaft auf True festlegen.

Hinweis

Sobald die Änderungsnachverfolgung für eine Tabelle aktiviert wurde, kann sie nicht mehr deaktiviert werden.

Weitere Informationen finden zur Verwendung von Power Apps: Erstellen und Bearbeiten von Tabellen mit Power Apps

Es gibt zwei Möglichkeiten, zu überprüfen, ob die Änderungsnachverfolgung für eine Tabelle aktiviert ist, mit der Dataverse-Web-API.

  1. Sie können EntityDefinitions mit folgender GET-Anforderung abfragen:

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

    Es gibt Systemtabellen mit aktivierter Änderungsnachverfolgung, beispielsweise Überwachung (Audit). Sie können die folgende Abfrage verwenden, um die vollständige Liste anzuzeigen:

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

    Weitere Informationen: Abfragetabellendefinition mithilfe der Web-API

  2. Diese Informationen finden Sie im Dokument des Web-API-$metadata-Dienstes. Die Anmerkung Org.OData.Capabilities.V1.ChangeTracking ist auf Entitätssätze gesetzt, die die Änderungsnachverfolgung aktiviert haben.

    Verwenden Sie diese Web-API-Abfrage, um Anmerkungen im Web-API-CDSL-Dienstdokument anzuzeigen:

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

    Diese Entitätssätze, die Tabellen darstellen, in denen die Änderungsnachverfolgung aktiviert ist, haben diese Anmerkungen:

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

    Weitere Informationen: Metadaten-Anmerkungen

Tabellen für die für die Änderungsverfolgung nicht gültig

Einige Tabellen können nicht für die Änderungsnachverfolgung aktiviert werden. Sie können überprüfen, ob eine Tabelle für die Änderungsnachverfolgung geeignet ist, indem Sie den verwalteten Eigenschaftswert EntityMetadata.CanChangeTrackingBeEnabled überprüfen. Um zu sehen, welche Tabellen nicht für die Änderungsnachverfolgung aktiviert werden können, verwenden Sie diese Web-API-Abfrage:

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

Weitere Informationen:

Abrufen von Änderungen für eine Tabelle über die Web-API

Änderungen in Tabellen können über Web-API-Anfragen nachverfolgt werden, indem Sie den Prefer: odata.track-changes-Header hinzufügen. Dieser Header fordert an, dass ein Deltalink zurückgegeben wird, der später verwendet werden kann, um Tabellenänderungen abzurufen.

Deltalinks sind opake, Service-generierte Links, die der Client verwendet, um nachfolgende Änderungen an einem Ergebnis abzurufen. Sie basieren auf einer definierenden Abfrage, die die Ergebnismenge beschreibt, für die Änderungen verfolgt werden. Zum Beispiel die Anforderung, die die Ergebnisse generiert hat, die den Deltalink enthalten. Der Delta-Link kodiert die Sammlung von Tabellen, für die Änderungen verfolgt werden, zusammen mit einem Startpunkt, von dem aus die Änderungen verfolgt werden sollen. Weitere Informationen: Oasis OData Version 4.0 – Delta-Links

Abrufen von Änderungen in Tabellen mit einem Web-API-Beispiel

In diesem Beispiel wird gezeigt, wie die an Kontotabellen vorgenommenen Änderungen mit der Web-API abgerufen werden.

Anforderung:

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

Antwort:

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

Der aus dem obigen Beispiel zurückgegebene @odata.deltaLink Uri kann verwendet werden, um Änderungen in Tabellen abzurufen. In diesem Beispiel wird eine neue Firma erstellt und eine vorhandene Firma gelöscht. Der Deltalink, der aus der vorherigen Anfrage zurückgegeben wurde, ruft diese Änderungen ab, wie im Beispiel unten.

Anforderung:

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

Antwort:

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

Die Antwort für den Deltalink, der in der ersten Änderungsnachverfolgungsanforderung zurückgegeben werden, enthält einen anderen Deltalink. Dieser Delta-Link hilft beim Abrufen aller nachfolgenden Änderungen in Tabellen. Eine leere JSON-Antwort wird zurückgegeben, wenn nach dem Aufruf der ersten Änderungsverfolgungsanfrage keine Tabellenänderungen aufgetreten sind.

Abrufen der Anzahl der in Tabellen vorgenommenen Änderungen über Web-API

$count können Sie dem Deltalink hinzufügen, der von der ursprünglichen Änderungsnachverfolgungsanforderung zurückgegeben wird, wie im Beispiel unten, um die Anzahl der vorgenommenen Änderungen abzurufen.

Anforderung:

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

Abfrageoptionen werden nicht unterstützt in der Änderungsnachverfolgungs-Web-API-Anforderung

Die Systemabfrageoptionen $filter, $orderby, $expand und $top werden nicht unterstützt, wenn der Prefer: odata.track-changes-Header in einer Web-API-Anforderung verwendet wird. Eine Fehlermeldung: The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled. wird zurückgegeben, wenn diese Abfrageoptionen in der Web-API-Anforderung verwendet werden.

Abrufen von Änderungen für eine Tabelle über die .NET-SDK

Wenn die Änderungsnachverfolgung für eine Tabelle aktiviert ist, können Sie die Nachricht RetrieveEntityChanges mit der RetrieveEntityChangesRequest-Klasse verwenden, um die Änderungen für diese Tabelle abzurufen.

Wenn diese Nachricht zum ersten Mal verwendet wird, werden alle Datensätze für die Tabelle zurückgegeben und diese Daten können zum Auffüllen des externen Speichers verwendet werden. Die Nachricht gibt zudem eine Versionsnummer zurück, die mit der nächsten Verwendung der RetrieveEntityChanges-Nachricht zurückgesendet wird, sodass nur Daten für Änderungen, die seit dieser Version aufgetreten sind, zurückgegeben werden.

Sie sollten beim Abrufen von Änderungen für eine Tabelle die folgenden Einschränkungen beachten:

  • Es wird nur eine Tabelle beim Abrufen von Änderungen verfolgt. Wenn RetrieveEntityChanges ohne Version/Token ausgeführt wird, behandelt der Server dies als Mindestversion des Systems, wobei alle Datensätze als neu zurückgegeben werden. Gelöschte Objekte werden nicht zurückgegeben.
  • Änderungen werden zurückgegeben, wenn das letzte Token innerhalb eines Standardwerts von 7 Tagen liegt. Diese Dauer wird durch den Wert der Spalte „ExpireChangeTrackingInDays“ der Organisationstabelle gesteuert und kann geändert werden. Wenn unverarbeitete Änderungen vorhanden sind, die älter als der konfigurierte Wert sind, löst das System eine Ausnahme aus.
  • Wenn ein Client einen Satz von Änderungen für eine Tabelle hat, z. B. Version 1, ein Datensatz erstellt und vor der nächsten Abfrage nach Änderungen gelöscht wird, erhält er das gelöschte Element, auch wenn er das Element zu Beginn nicht hatte.
  • Datensätze werden in der Reihenfolge abgerufen wie von der serverseitige Logik bestimmt. Normalerweise erhält der Aufrufende zuerst alle neuen oder aktualisierten Datensätze (sortiert nach Versionsnummer), gefolgt von den gelöschten Datensätzen. Wenn 3.000 Datensätze erstellt oder aktualisiert und 2.000 Datensätze gelöscht werden, gibt Dataverse eine Sammlung von 5.000 Datensätzen zurück, in der die ersten 3.000 Einträge die neuen oder aktualisierten Datensätze sind und die letzten 2.000 Einträge die gelöschten Datensätze.
  • Wenn die neue oder aktualisierte Elementsammlung größer als 5000 ist, kann der Benutzer durch die Sammlung blättern.
  • Der aufrufende Benutzer muss Lesezugriff auf Organisationsebene auf die Tabelle haben. Wenn der Benutzer eingeschränkten Lesezugriff hat, gibt das System einen Fehler bei der Berechtigungsprüfung aus.

.NET-SDK-Beispielcode

Der folgende Codeschnipsel zeigt, wie die Nachricht RetrieveEntityChanges verwendet wird, um die Änderungen für eine Tabelle abzurufen. Das vollständige Beispiel finden Sie unter Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung.

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;
}

Siehe auch

Definierter alternative Schlüssel für eine Tabelle
Verwenden Sie einen Alternativschlüssel, um auf einen Datensatz zu verweisen
Aktualisieren von Dynamics 365 mit externen Daten mithilfe von Upsert
Abfragen von Tabellendefinitionen mithilfe der Web-API

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).