Beispiel: Benutzerdefinierte ExportDataUsingFetchXmlToAnnotation-API

Artikel
06/10/2024

Dieses Beispiel zeigt, wie ein Plug-In geschrieben wird, das eine benutzerdefinierte API mit dem Namen sample_ExportDataUsingFetchXmlToAnnotation unterstützt. Sie können auf den Beispielcode unter PowerApps-Samples/dataverse/orgsvc/C#/ExportDataUsingFetchXmlToAnnotation/ zugreifen.

Das Plug-In stellt Logik für den Hauptvorgang der benutzerdefinierten API bereit. Die benutzerdefinierte sample_ExportDataUsingFetchXmlToAnnotation-API ruft Daten mithilfe des bereitgestellten FetchXML-Eingabeparameters ab und erstellt eine CSV-Datei. Anschließend erstellt es einen Anmerkungsdatensatz und gibt annotationid als AnnotationId-Antworteigenschaft zurück.

HINWEIS: Die Größe der Daten in der CSV-Datei sollte unter der in den Systemeinstellungen festgelegten Größenbeschränkung für Anhänge liegen. Andernfalls schlägt die Erstellung des Anhangs fehl.

Wie man dieses Beispiel ausführt

Um den in diesem Beispiel gefundenen Code auszuführen, müssen Sie zunächst eine benutzerdefinierte API in Ihrer Organisation erstellen.

Es gibt zwei Möglichkeiten, die benutzerdefinierte API zu erstellen:

Importieren der verwalteten Lösungsdatei
Benutzerdefinierte APIs erstellen

Importieren der verwalteten Lösungsdatei

Die ExportDataUsingFetchXmlToAnnotation_1_0_0_0_managed.zip in diesem Ordner enthält die benutzerdefinierte sample_ExportDataUsingFetchXmlToAnnotation-API, die diesen Code verwendet, sowie eine sample_CleanupExportedDataAnnotations-Bereinigungs-API. Sie können diese Lösungsdatei importieren, um die benutzerdefinierte API in Ihrer Organisation zu erstellen. Siehe Lösungen importieren für Anweisungen.

Verwenden Sie nach Abschluss des Tests die benutzerdefinierte sample_CleanupExportedDataAnnotations-API, um die erstellten Daten zu löschen, und löschen Sie die verwaltete Lösung, um die benutzerdefinierte API zu entfernen.

sample_ExportDataUsingFetchXmlToAnnotation ist eine ungebundene benutzerdefinierte API. Sie benötigt einen Eingabeparameter FetchXml, der zum Abrufen der Daten verwendet wird, und gibt die AnnotationId zurück, die Datensatz-ID des erstellten Anmerkungsdatensatzes, der die CSV-Dateidaten enthält.

Die sample_CleanupExportedDataAnnotations API hat keine Eingabe-/Ausgabeparameter.

Benutzerdefinierte APIs erstellen

Sie können auch die Plug-In-Assembly in diesem Projekt erstellen, die benutzerdefinierte API erstellen und den Plug-In-Schritt mit einer von mehreren Methoden zuordnen. Weitere Informationen: Eine benutzerdefinierte API erstellen

Diese Lösung enthält zwei benutzerdefinierte APIs. Das folgende JSON, das diese benutzerdefinierten APIs beschreibt, wurde mithilfe der Web-API abgerufen. Weitere Informationen: Daten zu benutzerdefinierten APIs abrufen

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

Wie dieses Beispiel funktioniert

Sie können entweder die Web-API oder das Dataverse SDK für .NET verwenden, um die benutzerdefinierte sample_ExportDataUsingFetchXmlToAnnotation-API zu verwenden.

SDK für .NET
Web-API

Sie können die Beispielanweisungen für den SDK für .NET-Schnellstart verwenden, um eine .NET Framework-Konsolenanwendung mit C# zu erstellen. Siehe Schnellstart: Eine SDK für .NET-Anforderung ausführen (C#)

Fügen Sie der Programmklasse die folgende statische Methode hinzu, um eine wiederverwendbare Methode zum Exportieren von Daten mit FetchXML to Annotation zu erstellen.

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

Ersetzen Sie den Code namens WhoAmIRequest durch den folgenden Code:
```
 var annotationId = ExportDataUsingFetchXmlToAnnotation(svc)
```

Um die benutzerdefinierte sample_ExportDataUsingFetchXmlToAnnotation API mit der Web-API zu verwenden, senden Sie eine POST-Anforderung an den API-Endpunkt. Sie können Insomnia verwenden, um diese Anforderung zu senden. Insomnia mit der Dataverse-Web-API verwenden

Anforderung:

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

Antwort:

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

Der Wert AnnotationId gibt den Datensatz in der Anmerkungstabelle an.

Veranschaulichung

So rufen Sie rekursiv Daten aus „fetch xml“ ab.
So erstellen Sie einen CSV-Anhang für eine Anmerkungsentität.
Wie Sie ein Plug-In zur Unterstützung einer benutzerdefinierten API schreiben
So wenden Sie eine benutzerdefinierte API mithilfe der Web-API an
So verwenden Sie eine benutzerdefinierte API mithilfe des SDK für .NET

Bereinigung

Um alle erstellten Daten zu bereinigen, verwenden Sie die benutzerdefinierte sample_CleanupExportedDataAnnotations-API-Aktion, um die erstellten Anmerkungsdatensätze zu löschen, und deinstallieren Sie dann die verwaltete Lösung.

sample_CleanupExportedDataAnnotations löscht alle Anmerkungsdatensätze, die die folgenden Kriterien erfüllen:

Spalte	Wert
`subject`	`Export Data Using FetchXml To Csv`
`filename`	`exportdatausingfetchxml.csv`

Sie können entweder die Web-API oder das Dataverse SDK für .NET verwenden, um die benutzerdefinierte sample_CleanupExportedDataAnnotations-API zu verwenden.

SDK für .NET
Web-API

Sie können die Beispielanweisungen für den SDK für .NET-Schnellstart verwenden, um eine .NET-Konsolenanwendung mit C# zu erstellen. Siehe Schnellstart: Eine SDK für .NET-Anforderung ausführen (C#)
Fügen Sie der Programmklasse die folgende statische Methode hinzu, um eine wiederverwendbare Methode zum Löschen der erstellten Daten mithilfe der benutzerdefinierten sample_ExportDataUsingFetchXmlToAnnotation-API zu erstellen.
```
static void CleanupExportedDataAnnotations(IOrganizationService service)
{
    var req = new OrganizationRequest("sample_CleanupExportedDataAnnotations")

   service.Execute(req);
}
```
Ersetzen Sie den Code namens WhoAmIRequest durch den folgenden Code:
```
 CleanupExportedDataAnnotations(svc)
```

Um die benutzerdefinierte sample_CleanupExportedDataAnnotations API mit der Web-API zu verwenden, senden Sie eine POST-Anforderung an den API-Endpunkt. Sie können Insomnia verwenden, um diese Anforderung zu senden. Insomnia mit der Dataverse-Web-API verwenden