Extraire l’historique de modifications de données auditées

Les deux requêtes suivantes renvoient la même réponse.

La suivante filtre selon la propriété _userid_value de l’enregistrement d’audit où la valeur correspond à <user id>.

Demande :

GET [Organization URI]/api/data/v9.2/audits?$select=_objectid_value,objecttypecode,createdon,_userid_value&$orderby=createdon desc&$filter=operation eq 3 and objecttypecode eq 'contact' and _userid_value eq '<user id>'

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null
Prefer: odata.include-annotations="*" 

La requête suivante accède à la collection d’enregistrements d’audit pour un utilisateur spécifique avec la propriété de navigation lk_audit_userid affectée à une valeur de collection de la table systemuser où la valeur systemuserid correspond à <user id>.

Demande :

GET [Organization URI]/api/data/v9.2/systemusers(<user id>)/lk_audit_userid?$select=_objectid_value,objecttypecode,createdon,_userid_value&$orderby=createdon desc&$filter=operation eq 3 and objecttypecode eq 'contact'

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null
Prefer: odata.include-annotations="*" 

Réponse :

HTTP/1.1 200 OK
Preference-Applied: odata.include-annotations="*"

{
  "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#audits(_objectid_value,objecttypecode,createdon,_userid_value)",
  "@Microsoft.Dynamics.CRM.totalrecordcount": -1,
  "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
  "value": [
    {
      "_objectid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
      "_objectid_value": "0e76dc8a-41b5-ec11-983f-0022482bf046",
      "objecttypecode@OData.Community.Display.V1.FormattedValue": "Contact",
      "objecttypecode": "contact",
      "createdon@OData.Community.Display.V1.FormattedValue": "5/12/2022 3:19 PM",
      "createdon": "2022-05-12T22:19:12Z",
      "_userid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
      "_userid_value@OData.Community.Display.V1.FormattedValue": "FirstName LastName",
      "_userid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e"
    },
    < Other results truncated for brevity>
  ]
}

Les deux méthodes statiques suivantes affichent le nombre d’enregistrements de contacts supprimés pour l’utilisateur spécifié. Ces requêtes utilisent l’agrégation, elles ne sont donc pas limitées à 5 000 résultats. Cependant, ils sont limités à la limite supérieure de 50 000 enregistrements pour l’agrégation.

ShowNumberContactsDeletedByUserQE utilise QueryExpression.

/// <summary>
/// Shows the number of contacts deleted by a user.
/// </summary>
/// <param name="svc">IOrganizationService to use</param>
/// <param name="systemuserid">The user's id.</param>
static void ShowNumberContactsDeletedByUserQE(
    IOrganizationService svc,
    Guid systemuserid)
{
    var columnSet = new ColumnSet("auditid");

    //Adding Attribute expression to use aggregation
    columnSet
        .AttributeExpressions
        .Add(new XrmAttributeExpression(
            attributeName: "auditid",
            aggregateType: XrmAggregateType.Count,
            alias: "count"));

    var query =
    new QueryExpression(entityName: "audit")
    {
        ColumnSet = columnSet
    };

    query.Criteria.AddCondition(
        attributeName: "userid",
        conditionOperator: ConditionOperator.Equal,
        values: systemuserid);

    query.Criteria.AddCondition(
        attributeName: "operation",
        conditionOperator: ConditionOperator.Equal,
        values: 3);

    query.Criteria.AddCondition(
        attributeName: "objecttypecode",
        conditionOperator: ConditionOperator.Equal,
        values: "contact");

    EntityCollection records =
        svc.RetrieveMultiple(query);

    int number = (int)
        ((AliasedValue)records
        .Entities[0]["count"])
        .Value;

    Console.WriteLine(
        $"User has deleted {number} contact records");
}

En savoir plus sur :

• Générer des requêtes avec QueryExpression

ShowNumberContactsDeletedByUserFetchXml utilise FetchExpression avec une requête composée à l’aide de FetchXml.

/// <summary>
/// Shows the number of contacts deleted by a user.
/// </summary>
/// <param name="svc">IOrganizationService instance to use</param>
/// <param name="systemuserid">The user's id.</param>
static void ShowNumberContactsDeletedByUserFetchXml(
IOrganizationService svc,
Guid systemuserid)
{
    string fetchXml = $@"<fetch 
    distinct='false' 
    mapping='logical' 
    aggregate='true'>
<entity name='audit'>
    <attribute name='auditid' 
        aggregate='count' 
        alias='count' />
    <filter>
        <condition attribute='userid' 
            operator='eq' 
            value='{systemuserid}' />
        <condition attribute='operation' 
            operator='eq' 
            value='3' />
        <condition attribute='objecttypecode' 
            operator='eq' 
            value='2' />
    </filter>
</entity>
</fetch>";

    int number;

    try
    {
        EntityCollection records =
        svc.RetrieveMultiple(new FetchExpression(fetchXml));

        number = (int)
            ((AliasedValue)records
            .Entities[0]["count"])
            .Value;
    }
    catch (Exception)
    {
        throw;
    }
    Console.WriteLine(
        $"User has deleted {number} contact records");
}

En savoir plus sur :

• Interroger des données à l’aide de FetchXml
• Agréger des données à l’aide de FetchXml

RetrieveAuditDetails est une fonction liée à la table d’audit. Incluez l’en-tête de requête Prefer: odata.include-annotations="*", vous obtiendrez des valeurs mises en forme.

L’exemple suivant montre le ComplexType AttributeAuditDetail renvoyé lorsque l’parentaccountid est défini sur un enregistrement de type account.

Demande :

GET [Organization URI]/api/data/v9.2/audits(12869c65-d7d3-ec11-b656-281878f0eba9)/Microsoft.Dynamics.CRM.RetrieveAuditDetails

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null
Prefer: odata.include-annotations="*" 

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RetrieveAuditDetailsResponse",
 "AuditDetail": {
  "@odata.type": "#Microsoft.Dynamics.CRM.AttributeAuditDetail",
  "InvalidNewValueAttributes": [],
  "LocLabelLanguageCode": 0,
  "DeletedAttributes": {
   "Count": 0,
   "Keys": [],
   "Values": []
  },
  "OldValue": {
   "@odata.type": "#Microsoft.Dynamics.CRM.account"
  },
  "NewValue": {
   "@odata.type": "#Microsoft.Dynamics.CRM.account",
   "_parentaccountid_value@OData.Community.Display.V1.FormattedValue": "A. Datum Corporation",
   "_parentaccountid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "parentaccountid",
   "_parentaccountid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "account",
   "_parentaccountid_value": "d249d106-38b5-ec11-983f-002248296cd0"
  }
 }
}

En savoir plus sur :

• Fonction RetrieveAuditDetails
• ComplexType RetrieveAuditDetailsResponse

La méthode statique ShowAuditDetail suivante renvoie les détails d’audit pour tout type de détails d’audit pouvant être suivis par un enregistrement d’audit.

/// <summary>
/// Returns audit details for the specified audit record
/// </summary>
/// <param name="svc">The IOrganizationService instance to use.</param>
/// <param name="auditid">The auditid for the audit record.</param>
static void ShowAuditDetail(
    IOrganizationService svc,
    Guid auditid)
{

    RetrieveAuditDetailsRequest req =
                new RetrieveAuditDetailsRequest
                {
                    AuditId = auditid
                };

    RetrieveAuditDetailsResponse resp =
        (RetrieveAuditDetailsResponse)svc.Execute(req);

    DisplayAuditDetail(resp.AuditDetail);
}

Méthode DisplayAuditDetail

La méthode statique DisplayAuditDetail renvoie différents détails sur la console en fonction du type de détail d’audit. Cette méthode est utilisée par d’autres exemples de SDK pour .NET sur cette page.

/// <summary>
/// Displays properties of the different classes derived from AuditDetail
/// </summary>
/// <param name="auditDetail">The instance of a type derived from AuditDetail</param>
static void DisplayAuditDetail(AuditDetail auditDetail)
{
    switch (auditDetail)
    {
        case AttributeAuditDetail aad:

            Entity oldRecord = aad.OldValue;
            Entity newRecord = aad.NewValue;
            List<string> oldKeys = new List<string>();

            //Look for changed or deleted values that are included in the OldValue collection
            oldRecord.Attributes.Keys.ToList().ForEach(k =>
            {
                if (oldRecord.FormattedValues.Keys.Contains(k))
                {
                    if (newRecord.FormattedValues.Contains(k))
                    {
                        Console.WriteLine(
                            $"\tChange:{k}:{oldRecord.FormattedValues[k]} => " +
                            $"{newRecord.FormattedValues[k]}");
                    }
                    else
                    {

                        Console.WriteLine($"\tDeleted:{k}:" +
                            $"{oldRecord.FormattedValues[k]}");
                    }
                }
                else
                {
                    if (newRecord.Attributes.Keys.Contains(k))
                    {

                        Console.WriteLine($"\tChange:{k}:{oldRecord[k]} => " +
                            $"{newRecord[k]}");
                    }
                    else
                    {
                        Console.WriteLine($"\tDeleted:{k}:{oldRecord[k]}");
                    }
                }

                oldKeys.Add(k); //Add to list so we don't check again
            });

            //Look for New values that are only in the NewValues collection
            newRecord.Attributes.Keys.ToList().ForEach(k =>
            {
                if (!oldKeys.Contains(k))//Exclude any keys for changed or deleted values
                {
                    if (newRecord.FormattedValues.Keys.Contains(k))
                    {
                        Console.WriteLine($"\tNew Value:{k} => " +
                            $"{newRecord.FormattedValues[k]}");
                    }
                    else
                    {
                        Console.WriteLine($"\tNew Value:{k}:{newRecord[k]}");
                    }
                }
            });
            break;

        case ShareAuditDetail sad:
            Console.WriteLine($"\tUser: {sad.Principal.Name}");
            Console.WriteLine($"\tOld Privileges: {sad.OldPrivileges}");
            Console.WriteLine($"\tNew Privileges: {sad.NewPrivileges}");
            break;

        //Applies to operations on N:N relationships
        case RelationshipAuditDetail rad:
            Console.WriteLine($"\tRelationship Name :{rad.RelationshipName }");
            Console.WriteLine($"\tRecords:");
            rad.TargetRecords.ToList().ForEach(y =>
            {
                Console.WriteLine($"\tTarget Record :{y.Name}");
            });
            break;

        //Only applies to role record
        case RolePrivilegeAuditDetail rpad:

            List<string> newRolePrivileges = new List<string>();
            rpad.NewRolePrivileges.ToList().ForEach(y =>
            {
                if (y != null)
                {
                    newRolePrivileges.Add(
                    $"\t\tPrivilege Id:{y.PrivilegeId} Depth:{y.Depth}\n");
                }
            });

            List<string> oldRolePrivileges = new List<string>();
            rpad.OldRolePrivileges.ToList().ForEach(y =>
            {
                if (y != null)
                {
                    oldRolePrivileges.Add(
                    $"\t\tPrivilege Id:{(y.PrivilegeId)} Depth:{y.Depth}\n");
                }
            });

            List<string> invalidNewPrivileges = new List<string>();
            rpad.InvalidNewPrivileges.ToList().ForEach(y =>
            {
                if (y != null)
                {
                    invalidNewPrivileges.Add(
                    $"\t\tGuid:{y}\n");
                }
            });

            Console.WriteLine($"\tNew Role Privileges:\n{string.Join(string.Empty, newRolePrivileges.ToArray())}");
            Console.WriteLine($"\tOld Role Privileges:\n{string.Join(string.Empty, oldRolePrivileges.ToArray())}");
            Console.WriteLine($"\tInvalid New Privileges:\n{string.Join(string.Empty, invalidNewPrivileges.ToArray())}"); ;
            break;

        //Only applies for systemuser record
        case UserAccessAuditDetail uaad:
            Console.WriteLine($"\tAccess Time:{uaad.AccessTime}");
            Console.WriteLine($"\tInterval:{uaad.Interval}");
            break;
    }
}

En savoir plus sur :

• Classe RetrieveAuditDetailsRequest
• Classe RetrieveAuditDetailsResponse
• Méthode IOrganizationService.Execute

Cet exemple renvoie un seul historique des modifications audité pour la colonne description d’un enregistrement de table account.

Demande :

GET [Organization URI]/api/data/v9.2/RetrieveAttributeChangeHistory(Target=@target,AttributeLogicalName=@attributeLogicalName,PagingInfo=@paginginfo)?
@target={ '@odata.id':'accounts(611e7713-68d7-4622-b552-85060af450bc)'}
&@attributeLogicalName='description'
&@paginginfo={
   "PageNumber": 1,
   "Count": 1,
   "ReturnTotalRecordCount": true
}

Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Réponse :

HTTP/1.1 200 OK

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RetrieveAttributeChangeHistoryResponse",
 "AuditDetailCollection": {
  "MoreRecords": true,
  "PagingCookie": "<cookie page=\"1\"><cookieExtensions ContinuationToken=\"{&quot;pageNumber&quot;:2,&quot;continuationToken&quot;:&quot;[{\\&quot;compositeToken\\&quot;:{\\&quot;token\\&quot;:null,\\&quot;range\\&quot;:{\\&quot;min\\&quot;:\\&quot;3A800000000000000000000000000000\\&quot;,\\&quot;max\\&quot;:\\&quot;3B000000000000000000000000000000\\&quot;}},\\&quot;orderByItems\\&quot;:[{\\&quot;item\\&quot;:\\&quot;2022-05-13T22:06:46.6175613Z\\&quot;}],\\&quot;rid\\&quot;:\\&quot;CVoNAJIidnNsmz0AAADwAw==\\&quot;,\\&quot;skipCount\\&quot;:0,\\&quot;filter\\&quot;:null}]&quot;}\" /></cookie>",
  ,
  "TotalRecordCount": 3,
  "AuditDetails": [
   {
    "@odata.type": "#Microsoft.Dynamics.CRM.AttributeAuditDetail",
    "InvalidNewValueAttributes": [],
    "LocLabelLanguageCode": 0,
    "DeletedAttributes": {
     "Count": 0,
     "Keys": [],
     "Values": []
    },
    "OldValue": {
     "@odata.type": "#Microsoft.Dynamics.CRM.account",
     "description": "Old description value"
    },
    "NewValue": {
     "@odata.type": "#Microsoft.Dynamics.CRM.account",
     "description": "New description value"
    }
   }
  ]
 }
}

En savoir plus sur :

• Fonction RetrieveAttributeChangeHistory
• ComplexType RetrieveAttributeChangeHistoryResponse
• ComplexType AuditDetailCollection

La méthode statique ShowAttributeChangeHistory ci-dessous renvoie les 20 premières modifications auditées pour la colonne spécifiée dans l’enregistrement spécifié.

Cette méthode dépend de l’exemple de Méthode DisplayAuditDetail inclus dans l’exemple Message RetrieveAuditDetails sur cette page.

/// <summary>
/// Returns up to 20 audited changes for the specified column of a specified record.
/// </summary>
/// <param name="svc">The IOrganizationService instance to use.</param>
/// <param name="target">The specified record.</param>
/// <param name="columnLogicalName">The specified column.</param>
static void ShowAttributeChangeHistory(IOrganizationService svc,
            EntityReference target,
            string columnLogicalName)
{
    RetrieveAttributeChangeHistoryRequest req =
        new RetrieveAttributeChangeHistoryRequest
        {
            Target = target,
            AttributeLogicalName = columnLogicalName,
            PagingInfo = new PagingInfo
            {
                PageNumber = 1,
                Count = 20,
                ReturnTotalRecordCount = true
            }
        };

    RetrieveAttributeChangeHistoryResponse resp =
        (RetrieveAttributeChangeHistoryResponse)svc.Execute(req);
    var auditDetailCollection = resp.AuditDetailCollection;

    int recordsReturned = auditDetailCollection.AuditDetails.Count;
    int totalRecords = auditDetailCollection.TotalRecordCount;
    Console.WriteLine($"Retrieved {recordsReturned} of " +
        $"{totalRecords} auditdetail records.");

    auditDetailCollection.AuditDetails.ToList().ForEach(x =>
    {

        Entity auditRecord = x.AuditRecord;

        Console.WriteLine($"Change Date: " +
            $"{auditRecord.FormattedValues["createdon"]}");
        Console.WriteLine($"Change By: " +
            $"{((EntityReference)auditRecord["userid"]).Name}");
        Console.WriteLine($"Action: " +
            $"{auditRecord.FormattedValues["action"]}");
        Console.WriteLine($"Operation: " +
            $"{auditRecord.FormattedValues["operation"]}");

        DisplayAuditDetail(auditDetail: x);

        Console.WriteLine();
    });
}

En savoir plus sur :

• Classe RetrieveAttributeChangeHistoryRequest
• Classe RetrieveAttributeChangeHistoryResponse
• Méthode IOrganizationService.Execute

L’exemple suivant renvoie uniquement les deux premières des quatre modifications d’un enregistrement de compte.

Demande :

GET [Organization URI]/api/data/v9.2/RetrieveRecordChangeHistory(Target=@target,PagingInfo=@paginginfo)?
@target={ '@odata.id':'accounts(611e7713-68d7-4622-b552-85060af450bc)'}
&@paginginfo={
   "PageNumber": 1,
   "Count": 2,
   "ReturnTotalRecordCount": true
}
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0
If-None-Match: null

Réponse :

HTTP/1.1 200 OK

{
 "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RetrieveRecordChangeHistoryResponse",
 "AuditDetailCollection": {
  "MoreRecords": true,
  "PagingCookie": "<cookie page=\"1\"><cookieExtensions ContinuationToken=\"{&quot;pageNumber&quot;:2,&quot;continuationToken&quot;:&quot;[{\\&quot;compositeToken\\&quot;:{\\&quot;token\\&quot;:null,\\&quot;range\\&quot;:{\\&quot;min\\&quot;:\\&quot;38000000000000000000000000000000\\&quot;,\\&quot;max\\&quot;:\\&quot;38800000000000000000000000000000\\&quot;}},\\&quot;orderByItems\\&quot;:[{\\&quot;item\\&quot;:\\&quot;2022-05-13T22:06:27.8029732Z\\&quot;}],\\&quot;rid\\&quot;:\\&quot;CVoNAJIidnPOnT0AAAAICA==\\&quot;,\\&quot;skipCount\\&quot;:0,\\&quot;filter\\&quot;:null}]&quot;}\" /></cookie>",
  "TotalRecordCount": 4,
  "AuditDetails": [
   {
    "@odata.type": "#Microsoft.Dynamics.CRM.AttributeAuditDetail",
    "InvalidNewValueAttributes": [],
    "LocLabelLanguageCode": 0,
    "DeletedAttributes": {
     "Count": 0,
     "Keys": [],
     "Values": []
    },
    "OldValue": {
     "@odata.type": "#Microsoft.Dynamics.CRM.account",
     "description": "Old description value"
    },
    "NewValue": {
     "@odata.type": "#Microsoft.Dynamics.CRM.account",
     "description": "New description value"
    }
   },
   {
    "@odata.type": "#Microsoft.Dynamics.CRM.AttributeAuditDetail",
    "InvalidNewValueAttributes": [],
    "LocLabelLanguageCode": 0,
    "DeletedAttributes": {
     "Count": 0,
     "Keys": [],
     "Values": []
    },
    "OldValue": {
     "@odata.type": "#Microsoft.Dynamics.CRM.account",
     "_ownerid_value@OData.Community.Display.V1.FormattedValue": "FirstName LastName",
     "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
     "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "systemuser",
     "_ownerid_value": "4026be43-6b69-e111-8f65-78e7d1620f5e"
    },
    "NewValue": {
     "@odata.type": "#Microsoft.Dynamics.CRM.account",
     "_ownerid_value@OData.Community.Display.V1.FormattedValue": "TeamName",
     "_ownerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "ownerid",
     "_ownerid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "team",
     "_ownerid_value": "39e0dbe4-131b-e111-ba7e-78e7d1620f5e"
    }
   }
  ]
 }
}

En savoir plus sur :

• Fonction RetrieveRecordChangeHistory
• ComplexType RetrieveRecordChangeHistoryResponse
• ComplexType PagingInfo

Cette méthode statique ShowRetrieveRecordChangeHistory exécute le message RetrieveRecordChangeHistory pour un enregistrement spécifié et traite la réponse.

Pour chaque enregistrement d’audit, il affiche les propriétés et utilise l’exemple Méthode DisplayAuditDetail défini dans le Message RetrieveAuditDetails sur cette page pour afficher les détails.

/// <summary>
/// Shows the results of the RetrieveRecordChangeHistory message
/// </summary>
/// <param name="svc">The IOrganizationService instance to use</param>
/// <param name="record">A reference to a record of a table enabled for auditing</param>
static void ShowRetrieveRecordChangeHistory(
    IOrganizationService svc, 
    EntityReference record)
{
    var req = new RetrieveRecordChangeHistoryRequest
    {
        Target = record,
        PagingInfo = new PagingInfo
        {
            PageNumber = 1,
            Count = 20,
            ReturnTotalRecordCount = true
        }
    };

    var resp = (RetrieveRecordChangeHistoryResponse)svc.Execute(req);
    var auditDetailCollection = resp.AuditDetailCollection;

    int recordsReturned = auditDetailCollection.AuditDetails.Count;
    int totalRecords = auditDetailCollection.TotalRecordCount;
    Console.WriteLine($"Retrieved {recordsReturned} of {totalRecords} auditdetail records.");

    auditDetailCollection.AuditDetails.ToList().ForEach(x =>
    {

        Entity auditRecord = x.AuditRecord;

        Console.WriteLine($"Change Date: {auditRecord.FormattedValues["createdon"]}");
        Console.WriteLine($"Change By: {((EntityReference)auditRecord["userid"]).Name}");
        Console.WriteLine($"Action: {auditRecord.FormattedValues["action"]}");
        Console.WriteLine($"Operation: {auditRecord.FormattedValues["operation"]}");

        DisplayAuditDetail(auditDetail: x);
        
        Console.WriteLine();
    });
}

En savoir plus sur :

• Classe RetrieveRecordChangeHistoryRequest
• Classe RetrieveRecordChangeHistoryResponse
• Classe PagingInfo
• Méthode IOrganizationService.Execute
• Exemple : auditer les modifications des données d’entité.