Freigeben über

Synchronisieren von Daten mit externen Systemen mithilfe der Änderungsnachverfolgung

Das Feature zur Änderungsnachverfolgung in Microsoft Dataverse bietet eine Möglichkeit, Daten effizient zu synchronisieren, indem ermittelt wird, welche Daten seit der ersten Extraktion oder letzten Synchronisierung der Daten geändert wurden. Dieser Artikel beschreibt, wie Sie Änderungen für eine Tabelle aktivieren und abrufen können.

Aktivieren der Änderungsverfolgung für eine Tabelle

Stellen Sie vor dem Abrufen der Änderungen für eine Tabelle sicher, dass die Änderungsnachverfolgung 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 ".

Legen Sie diese Eigenschaft programmgesteuert fest, indem Sie die Eigenschaft EntityMetadata.ChangeTrackingEnabled auf True setzen.

Anmerkung

Nachdem Sie die Änderungsnachverfolgung für eine Tabelle aktiviert haben, können Sie sie nicht deaktivieren.

Weitere Informationen zur Verwendung von Power Apps finden Sie unter Erstellen und Bearbeiten von Tabellen mit Power Apps.

Verwenden Sie eine der folgenden Methoden, um zu überprüfen, ob die Änderungsnachverfolgung für eine Tabelle mithilfe der Dataverse-Web-API aktiviert ist:

  1. Abfrage EntityDefinitions mithilfe der folgenden GET Anforderung:

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

    Einige Systemtabellen haben die Änderungsnachverfolgung aktiviert, z. B. Audit (Prüfung). Verwenden Sie die folgende Abfrage, 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 finden Sie unter Abfragetabellendefinitionen mithilfe der Web-API.

  2. Überprüfen Sie das Web-API-$metadata Dienstdokument. 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

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

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

    Weitere Informationen finden Sie unter Metadatenanmerkungen.

Tabellen, die nicht für die Änderungsverfolgung geeignet sind

Sie können die Änderungsnachverfolgung für einige Tabellen nicht aktivieren. Um zu überprüfen, ob eine Tabelle für die Änderungsnachverfolgung berechtigt ist, überprüfen Sie den Wert der verwalteten Eigenschaft "EntityMetadata.CanChangeTrackingBeEnabled ". 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

Sie können änderungen, die in Tabellen vorgenommen wurden, mithilfe von Web-API-Anforderungen nachverfolgen, die den Prefer: odata.track-changes Header enthalten. Dieser Header fordert an, dass eine Delta-Verknüpfung zurückgegeben wird, die Sie später zum Abrufen von Tabellenänderungen verwenden können.

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 finden Sie unter Oasis OData Version 4.0 – Delta Links.

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

In diesem Beispiel wird gezeigt, wie Änderungen abgerufen werden, die für die Kontotabelle mithilfe der Web-API vorgenommen wurden.

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

Verwenden Sie den @odata.deltaLink aus dem vorherigen Beispiel zurückgegebenen URI, um Änderungen in Tabellen abzurufen. In diesem Beispiel haben Sie ein neues Konto erstellt und ein vorhandenes Konto gelöscht. Die von der vorherigen Anforderung zurückgegebene Delta-Verknüpfung ruft diese Änderungen ab, wie im folgenden Beispiel gezeigt.

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. Wenn nach der anfänglichen Änderungsnachverfolgungsanforderung keine Tabellenänderungen vorgenommen werden, enthält die Antwort leere JSON.If no table changes occur after the initial change tracking request, the response contains empty JSON.

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

Um die Anzahl der Änderungen abzurufen, fügen Sie $count dem Delta-Link hinzu, der von der ursprünglichen Änderungsnachverfolgungsanforderung zurückgegeben wird, wie im folgenden Beispiel gezeigt.

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

Systemabfrageoptionen $filter, $orderby, $expandund $top werden nicht unterstützt, wenn Sie den Prefer: odata.track-changes Header in einer Web-API-Anforderung verwenden. Wenn Sie diese Abfrageoptionen in der Web-API-Anforderung verwenden, erhalten Sie eine Fehlermeldung: The \"${filter|orderby|expand|top}\" query parameter isn't supported when Change Tracking is enabled..

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

Wenn Sie die Änderungsnachverfolgung für eine Tabelle aktivieren, verwenden Sie die Nachricht mit der RetrieveEntityChangesRetrieveEntityChangesRequest-Klasse , um die Änderungen für diese Tabelle abzurufen.

Wenn Sie diese Nachricht zum ersten Mal verwenden, werden alle Datensätze für die Tabelle zurückgegeben. Sie können diese Daten verwenden, um den externen Speicher aufzufüllen. Die Nachricht gibt auch eine Versionsnummer zurück, die Sie mit der nächsten Verwendung der RetrieveEntityChanges Nachricht zurücksenden, sodass nur Daten für diese Änderungen zurückgegeben werden, die seit der Rückgabe dieser Version aufgetreten sind.

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

  • Sie können nur eine Tabelle beim Abrufen von Änderungen nachverfolgen. Wenn Sie RetrieveEntityChanges ohne Version oder Token ausführen, behandelt der Server dies als die Mindestversion des Systems und gibt alle Datensätze als neu zurück. Gelöschte Objekte werden nicht zurückgegeben.
  • Änderungen werden zurückgegeben, wenn das letzte Token innerhalb eines Standardwerts von sieben Tagen liegt. Der Wert der Spalte ExpireChangeTrackingInDays in der Tabelle "Organization" steuert diese Dauer und kann geändert werden. Wenn nicht verarbeitete Änderungen älter als der konfigurierte Wert sind, löst das System eine Ausnahme aus.
  • Wenn ein Client über eine Reihe von Änderungen für eine Tabelle verfügt, zum Beispiel Version 1, wird ein Datensatz erstellt und gelöscht, bevor die nächste Abfrage nach Änderungen erfolgt. Der Client erhält das gelöschte Element, auch wenn sie es ursprünglich nicht hatten.
  • Datensätze werden in der Reihenfolge abgerufen, wie es die serverseitigen Logik bestimmt. Normalerweise ruft der Anrufer zuerst alle neuen oder aktualisierten Datensätze ab (sortiert nach Versionsnummer), gefolgt von 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 für Standardtabellen 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 Codeausschnitt zeigt, wie die Nachricht zum Abrufen der RetrieveEntityChanges Änderungen für eine Tabelle verwendet wird. 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

Definieren Sie 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

  • Last updated on