Exemple : API personnalisée ExportDataUsingFetchXmlToAnnotation

Article
03/29/2024

Cet exemple montre comment écrire un plug-in qui prend en charge une API personnalisée nommée sample_ExportDataUsingFetchXmlToAnnotation. Vous pouvez accéder à l’exemple de code à partir de PowerApps-Samples/dataverse/orgsvc/C#/ExportDataUsingFetchXmlToAnnotation/.

Le plug-in fournit une logique pour le fonctionnement principal de l’API personnalisée. L’API personnalisée sample_ExportDataUsingFetchXmlToAnnotation récupère les données à l’aide du paramètre d’entrée FetchXML fourni et crée un fichier CSV. Il crée ensuite un enregistrement d’annotation et renvoie la annotationid comme propriété de réponse AnnotationId.

REMARQUE : La taille des données dans le fichier CSV doit être inférieure à la limite de taille de pièce jointe spécifiée dans les paramètres système ; sinon la création de la pièce jointe échoue.

Comment exécuter cet exemple

Pour exécuter le code trouvé dans cet exemple, vous devez d’abord créer une API personnalisée dans votre organisation.

Il existe deux façons de créer une API personnalisée :

Importer le fichier de solution gérée
Créer et utiliser des API personnalisées

Importer le fichier de solution gérée

Le fichier ExportDataUsingFetchXmlToAnnotation_1_0_0_0_managed.zip dans ce dossier contient l’API personnalisée sample_ExportDataUsingFetchXmlToAnnotation qui utilise ce code, ainsi qu’une API de nettoyage sample_CleanupExportedDataAnnotations. Vous pouvez importer ce fichier de solution pour créer l’API personnalisée dans votre organisation. Voir Importer des solutions pour les consignes.

Une fois les tests terminés, utilisez l’API personnalisée sample_CleanupExportedDataAnnotations pour supprimer les données créées et supprimez le solution gérée pour supprimer l’API personnalisée.

sample_ExportDataUsingFetchXmlToAnnotation est une API personnalisée non liée. Il prend un paramètre d’entrée FetchXml, qui est utilisé pour récupérer les données et renvoie l’ID d’enregistrement AnnotationId de l’enregistrement d’annotation créé qui contient les données du fichier CSV.

L’API sample_CleanupExportedDataAnnotations n’a pas de paramètres d’entrée/sortie.

Créer et utiliser des API personnalisées

Vous pouvez également créer l’assembly de plug-in dans ce projet, créer l’API personnalisée et associer l’étape de plug-in à l’aide de plusieurs méthodes. Pour plus d’informations : Créer une API personnalisée

Il existe deux API personnalisées dans cette solution. Le JSON suivant décrivant ces API personnalisées a été récupéré à l’aide de l’API web. Pour plus d’informations : Extraire les données sur les API personnalisées

sample_ExportDataUsingFetchXmlToAnnotation

{
    "uniquename": "sample_ExportDataUsingFetchXmlToAnnotation",
    "allowedcustomprocessingsteptype@OData.Community.Display.V1.FormattedValue": "None",
    "allowedcustomprocessingsteptype": 0,
    "bindingtype@OData.Community.Display.V1.FormattedValue": "Global",
    "bindingtype": 0,
    "boundentitylogicalname": null,
    "description": "Exports data using the input Fetch Xml to CSV attaches to an annotation record.",
    "displayname": "Export Data Using Fetch XML to Annotation",
    "executeprivilegename": null,
    "isfunction@OData.Community.Display.V1.FormattedValue": "No",
    "isfunction": false,
    "isprivate@OData.Community.Display.V1.FormattedValue": "No",
    "isprivate": false,
    "workflowsdkstepenabled@OData.Community.Display.V1.FormattedValue": "No",
    "workflowsdkstepenabled": false,
    "customapiid": "bd8ffcee-5a38-4d0a-b296-6848c94dd22e",
    "iscustomizable": {
        "Value": true,
        "CanBeChanged": true,
        "ManagedPropertyLogicalName": "iscustomizableanddeletable"
    },
    "CustomAPIRequestParameters": [
        {            
            "uniquename": "FetchXml",
            "name": "Fetch Xml",
            "description": "Fetch XML which is used to fetch all data and export to CSV",
            "displayname": "Fetch Xml",
            "type@OData.Community.Display.V1.FormattedValue": "String",
            "type": 10,
            "logicalentityname": null,
            "isoptional@OData.Community.Display.V1.FormattedValue": "No",
            "isoptional": false
        }
    ],
    "CustomAPIResponseProperties": [
        {
            "uniquename": "AnnotationId",
            "name": "Annotation Id",
            "description": "Id of the created annotation entity record.",
            "displayname": "Annotation Id",
            "type@OData.Community.Display.V1.FormattedValue": "Guid",
            "type": 12,
            "logicalentityname": null
        }
    ],
    "PluginTypeId": {
        "typename": "PowerApps.Samples.ExportDataUsingFetchXmlToAnnotationPlugin",
        "version": "1.0.0.0",
        "name": "PowerApps.Samples.ExportDataUsingFetchXmlToAnnotationPlugin",
        "assemblyname": "ExportDataUsingFetchXmlToAnnotation"
    }
}

sample_CleanupExportedDataAnnotations

{
    "uniquename": "sample_CleanupExportedDataAnnotations",
    "allowedcustomprocessingsteptype@OData.Community.Display.V1.FormattedValue": "None",
    "allowedcustomprocessingsteptype": 0,
    "bindingtype@OData.Community.Display.V1.FormattedValue": "Global",
    "bindingtype": 0,
    "boundentitylogicalname": null,
    "description": "Clean Up Exported Data Annotations",
    "displayname": "Clean Up Exported Data Annotations",
    "executeprivilegename": null,
    "isfunction@OData.Community.Display.V1.FormattedValue": "No",
    "isfunction": false,
    "isprivate@OData.Community.Display.V1.FormattedValue": "No",
    "isprivate": false,
    "workflowsdkstepenabled@OData.Community.Display.V1.FormattedValue": "No",
    "workflowsdkstepenabled": false,
    "iscustomizable": {
        "Value": true,
        "CanBeChanged": true,
        "ManagedPropertyLogicalName": "iscustomizableanddeletable"
    },
    "CustomAPIRequestParameters": [],
    "CustomAPIResponseProperties": [],
    "PluginTypeId": {
        "typename": "PowerApps.Samples.CleanUpExportedDataAnnotationsPlugin",
        "version": "1.0.0.0",
        "name": "PowerApps.Samples.CleanUpExportedDataAnnotationsPlugin",
        "assemblyname": "ExportDataUsingFetchXmlToAnnotation"
    }
}

Utiliser cet exemple

Vous pouvez utiliser l’API web ou le service d’organisation avec le SDK Dataverse pour .NET pour utiliser l’API personnalisée sample_ExportDataUsingFetchXmlToAnnotation.

SDK pour .NET
API web

Vous pouvez utiliser les exemples Démarrage rapide du SDK pour .NET pour créer une application console .NET Framework avec C#. Voir Démarrage rapide : exécuter une requête SDK pour .NET (C#)

Ajoutez la méthode statique suivante à la classe de programme pour créer une méthode réutilisable pour exporter des données à l’aide de FetchXML vers l’annotation.

static Guid ExportDataUsingFetchXmlToAnnotation(IOrganizationService service)
{
    var req = new OrganizationRequest("sample_ExportDataUsingFetchXmlToAnnotation")
    {
        ["FetchXml"] = @"<fetch version='1.0' output-format='xml-platform' mapping='logical'>
                        <entity name='account'>
                            <attribute name='accountid'/>
                            <attribute name='name'/>  
                        </entity>
                    </fetch>"
    };

    var resp = service.Execute(req);

    var annotationId = (Guid)resp["AnnotationId"];

    return annotationId;
}

Remplacez le code qui appelle WhoAmIRequest par le code suivant :
```
 var annotationId = ExportDataUsingFetchXmlToAnnotation(svc)
```

Pour utiliser l’API personnalisée sample_ExportDataUsingFetchXmlToAnnotation avec l’API web, envoyez une requête POST au point de terminaison d’API. Vous pouvez utiliser Insomnia pour envoyer cette requête. Utiliser Insomnia avec l’API Web Dataverse

Demande :

POST [Organization URI]/api/data/v9.2/sample_ExportDataUsingFetchXmlToAnnotation
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "FetchXml": "<fetch version='1.0' output-format='xml-platform' mapping='logical'>
                    <entity name='account'>
                        <attribute name='accountid'/>
                        <attribute name='name'/>  
                    </entity>
                </fetch>"
}

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; odata.metadata=minimal

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.sample_ExportDataUsingFetchXmlToAnnotation",
    "AnnotationId": "c9fdfe63-41e3-ed11-8845-0022480b2800"
}

La valeur AnnotationId indique l’enregistrement dans la table d’annotations.

Montre ce qui suit

Comment récupérer récursivement des données à partir de fetch xml.
Comment créer une pièce jointe csv à l’entité d’annotation.
Comment écrire un plug-in pour prendre en charge une API personnalisée
Comment utiliser une API personnalisée à l’aide de l’API Web
Comment utiliser une fonction d’API personnalisée à l’aide du SDK pour .NET

Nettoyer

Pour nettoyer toutes les données créées, utilisez l’action d’API personnalisée sample_CleanupExportedDataAnnotations pour supprimer les enregistrements d’annotation créés, puis désinstallez la solution gérée.

sample_CleanupExportedDataAnnotations supprime tous les enregistrements d’annotation qui répondent aux critères suivants :

Colonne	active
`subject`	`Export Data Using FetchXml To Csv`
`filename`	`exportdatausingfetchxml.csv`

Vous pouvez utiliser l’API web ou le service d’organisation avec le SDK Dataverse pour .NET pour utiliser l’API personnalisée sample_CleanupExportedDataAnnotations.

SDK pour .NET
API web

Vous pouvez utiliser les exemples Démarrage rapide du SDK pour .NET pour créer une application console .NET avec C#. Voir Démarrage rapide : exécuter une requête SDK pour .NET (C#)
Ajoutez la méthode statique suivante à la classe de programme pour créer une méthode réutilisable pour supprimer les données créées à l’aide de l’API personnalisée sample_ExportDataUsingFetchXmlToAnnotation.
```
static void CleanupExportedDataAnnotations(IOrganizationService service)
{
    var req = new OrganizationRequest("sample_CleanupExportedDataAnnotations")

   service.Execute(req);
}
```
Remplacez le code qui appelle WhoAmIRequest par le code suivant :
```
 CleanupExportedDataAnnotations(svc)
```

Pour utiliser l’API personnalisée sample_CleanupExportedDataAnnotations avec l’API web, envoyez une requête POST au point de terminaison d’API. Vous pouvez utiliser Insomnia pour envoyer cette requête. Utiliser Insomnia avec l’API Web Dataverse