Vorgänge im Hintergrund (Vorschau)

  • Artikel

[Dieser Artikel ist Teil der Dokumentation zur Vorabversion und kann geändert werden.]

Verwenden Sie Hintergrundvorgänge, um Anforderungen zu senden, die Dataverse asynchron verarbeitet. Hintergrundvorgänge sind nützlich, wenn Sie keine Verbindung aufrechterhalten wollen, während eine Anfrage ausgeführt wird.

Wenn ein Vorgang im Hintergrund abgeschlossen ist, können Sie auf zwei Arten benachrichtigt werden:

Sie können das Ergebnis eines Hintergrundvorgangs auf zwei Arten abrufen:

Um eine Anfrage im Hintergrund auszuführen, muss der Vorgang als Custom-API definiert werden. Lernen Sie, wie man Custom-APIs erstellt und verwendet und Daten über Custom-APIs abruft.

Custom-APIs verwenden Plug-ins zur Durchführung von Datenvorgängen. Wie alle Dataverse-Plug-ins haben diese Plug-ins eine Ausführungszeit von zwei Minuten. Wenn Sie die Anfrage asynchron senden, haben Sie nicht mehr Ausführungszeit.

Erforderliche Rechte

Um einen Hintergrundvorgang auszuführen, muss der initiierende Benutzende über Lese- und Schreibzugriff auf die backgroundoperations-Tabelle verfügen. Weisen Sie die prvReadbackgroundoperation und prvWritebackgroundoperation--Rechte zu, um diesen Zugriff zu gewähren.

Lernen Sie, wie man eine Sicherheitsrolle bearbeitet.

Asynchrone Verarbeitung anfordern

Sie können asynchrone Anfragen im Hintergrund ausführen, indem Sie entweder das SDK für .NET oder die Web-API Dataverse verwenden.

Die Beispiele in diesem Artikel verwenden eine benutzerdefinierte API namens sample_ExportDataUsingFetchXmlToAnnotation. Diese benutzerdefinierte API wird in Beispiel: Benutzerdefinierte ExportDataUsingFetchXmlToAnnotation-API beschrieben.

Verwenden Sie die ExecuteBackgroundOperation-Nachricht.

Das SDK verfügt nicht über ExecuteBackgroundOperation Anfrage- und Antwortklassen. Bis diese Klassen hinzugefügt werden, verwenden Sie die Basisklassen OrganizationRequest und OrganizationResponse, wie in Nachrichten mit dem SDK für .NET verwenden beschrieben.

Die folgende Tabelle beschreibt die Eingabeparameter für die ExecuteBackgroundOperation-Nachricht.

Name des Dataflows Type Beschreibung
Request OrganizationRequest (Erforderlich) Enthält die Anfrage, die Sie asynchron verarbeiten lassen möchten. Die Dataverse-Nachricht für die Anfrage muss als Custom-API implementiert werden.
CallbackUri string (Optional) Dataverse sendet eine POST HTTP-Anfrage an diese URL, wenn der Vorgang abgeschlossen ist.

Die folgende Tabelle beschreibt die Ausgabeparameter für die ExecuteBackgroundOperation-Nachricht.

Name des Dataflows Type Beschreibung
BackgroundOperationId GUID Identifiziert die Tabellenzeile für den Hintergrundvorgang, mit der Sie die Verarbeitung Ihrer Anfrage überwachen oder abbrechen können.
Location string Identifiziert die URL der Statusmonitor-Ressource, die Sie verwenden können, um den Status Ihrer Anfrage abzurufen oder um sie abzubrechen.

Die folgende statische Methode verwendet ExecuteBackgroundOperation mit der benutzerdefinierten sample_ExportDataUsingFetchXmlToAnnotation API.

static void SendRequestAsynchronously(IOrganizationService service)
{
    //Create a request for message defined as a custom API to run in the background
    var asyncRequest = new OrganizationRequest("sample_ExportDataUsingFetchXmlToAnnotation")
    {
        Parameters =
        {
            {"FetchXml",  @"<fetch version='1.0'  
                                    output-format='xml-platform' 
                                    mapping='logical'>
                                <entity name='account'>
                                    <attribute name='accountid'/>
                                    <attribute name='name'/>  
                                </entity>
                            </fetch>" }
        }
    };

    //Create a request to execute the message in the background
    var request = new OrganizationRequest("ExecuteBackgroundOperation")
    {
        Parameters =
        {
            {"Request", asyncRequest }
        }
    };

    //Execute the background operation request
    var response = service.Execute(request);

    Console.WriteLine($"BackgroundOperationId: {response["BackgroundOperationId"]}");
    Console.WriteLine($"Location: {response["Location"]}");
}

Ausgabe:

BackgroundOperationId: <backgroundoperationid value>
Location: [Organization URI]/api/backgroundoperation/<backgroundoperationid value>

Erfahren Sie mehr über die IOrganizationService-Schnittstelle und wie Sie Nachrichten mit dem SDK für .NET verwenden.

Hintergrundvorgänge verwalten

Wenn Sie eine Anfrage senden, die im Hintergrund verarbeitet werden soll, enthält die Antwort zwei Werte, die für verschiedene Methoden stehen, mit denen Sie Hintergrundvorgänge überwachen oder abbrechen können.

Die Abfrage der Tabelle für Hintergrundvorgänge oder der Statusmonitor-Ressource zur Überprüfung von Anfragen ist allgemein als Statusabfrage bekannt. Wir empfehlen, übermäßige Abfragen zu vermeiden, da dies die Leistung beeinträchtigen kann. Wir empfehlen, Abfrage bei Bedarf in Intervallen von einer Minute oder mehr durchzuführen.

Tabelle der Hintergrundvorgänge

Die Tabelle der Hintergrundvorgänge enthält Informationen über Anfragen, die asynchron verarbeitet werden sollen. Diese Tabelle hat den logischen Namen backgroundoperation und den Entitätsmengennamen backgroundoperations. Erfahren Sie mehr über die Hintergrundoperation EntityType.

Die folgende Tabelle beschreibt die Spalten, die Sie verwenden können, um den Status von Hintergrundvorgängen zu verwalten.

Anzeigenname
Schemaname
Logischer Name		 Type Beschreibung
Hintergrundvorgang
BackgroundOperationId
backgroundoperationid		 Eindeutiger Bezeichner Der Primärschlüssel
Status
StateCode
backgroundoperationstatecode		 Auswahlliste Status des Hintergrundvorgangs

Optionen:
- Wert: 0, Label: Bereit
- Wert: 2, Label: Gesperrt
- Wert: 3, Label: Erledigt
Statusgrund
StatusCode
backgroundoperationstatuscode		 Auswahlliste Status des Hintergrundvorgangs

Optionen:
- Wert: 0, Label: Warten auf Ressourcen (Status:Bereit)
- Wert: 20, Label: In Bearbeitung (Status:Gesperrt)
- Wert: 22, Label: Wird abgebrochen (Status:Gesperrt)
- Wert: 30, Label: Erfolgreich (Status:Abgeschlossen)
- Wert: 31, Label: Fehlgeschlagen (Status:Abgeschlossen)
- Wert: 32, Label: Abgebrochen (Status:Abgeschlossen)
Name des Dataflows
Name
name		 String Die UniqueName der Custom-API, die für den Vorgang im Hintergrund verwendet wird
Anzeigename
DisplayName
displayname		 String Die DisplayName der Custom-API, die für den Vorgang im Hintergrund verwendet wird
Eingabe-Parameter
InputParameters
inputparameters		 Memo Die Eingabeparameter, die zum Starten des Vorgangs im Hintergrund bereitgestellt wurden

Diese Zeichenfolge ist ein serialisiertes JSON-Array aus Key und Value.
Ausgabeparameter
OutputParameters
outputparameters		 Memo Die Antwort des Hintergrundvorgangs

Diese Zeichenfolge ist ein serialisiertes JSON-Array aus Key und Value.
Anfangszeit
StartTime
starttime		 DateTime Wenn die Ausführung des Hintergrundvorgangs begonnen hat
Endzeit
EndTime
endtime		 DateTime Wenn die Ausführung des Hintergrundvorgangs beendet ist
Anzahl der Wiederholungsversuche
RetryCount
retrycount		 Ganzzahl Die Anzahl, wie oft der Vorgang im Hintergrund wiederholt wurde
Fehlercode
ErrorCode
errorcode		 Ganzzahl Der Fehlercode, wenn der Vorgang im Hintergrund fehlschlägt

Wenn der Fehler von Dataverse stammt, hat er einen ganzzahligen Wert, der einem der unter Webdienst-Fehlercodes aufgeführten Codes entspricht. Wenn der Fehler nicht von Dataverse herrührt, wird der Wert auf Null gesetzt.
Fehlermeldung
ErrorMessage
errormessage		 Memo Die Fehlermeldung, wenn der Vorgang im Hintergrund fehlschlägt
Ausführen als
RunAs
runas		 String Die systemuserid der der systemuser, die zum Ausführen des Hintergrundvorgangs verwendet werden
Erstellt am
CreatedOn
createdon		 DateTime Wenn der Datensatz erstellt wurde
Gültigkeitsdauer
TTLInSeconds
ttlinseconds		 Ganzzahl Lebenszeit in Sekunden, nach der der Datensatz automatisch gelöscht wird; der Standardwert ist 90 Tage

Abfrage der Tabelle der Hintergrundvorgänge

Achten Sie darauf, diese Spalten in Ihre Abfrage aufzunehmen:

  • name
  • backgroundoperationstatecode
  • backgroundoperationstatuscode
  • outputparameters
  • errorcode
  • errormessage

Wie Sie die Tabelle abfragen, hängt davon ab, ob Sie das SDK oder die Web-API verwenden.

static void PollBackgroundOperationRequest(IOrganizationService service, Guid backgroundOperationId)
{
    // List of columns that will help to get status, output and error details if any
    var columnSet = new ColumnSet(
        "name",
        "backgroundoperationstatecode",
        "backgroundoperationstatuscode",
        "outputparameters",
        "errorcode",
        "errormessage");

    try
    {
        // Get the entity with all the required columns
        var backgroundOperation = service.Retrieve("backgroundoperation", backgroundOperationId, columnSet);

        Console.WriteLine($"Name: {backgroundOperation["name"]}");
        Console.WriteLine($"State Code: {backgroundOperation.FormattedValues["backgroundoperationstatecode"]}");
        Console.WriteLine($"Status Code: {backgroundOperation.FormattedValues["backgroundoperationstatuscode"]}");
        Console.WriteLine($"Output Parameters:");

        // Deserialize the Output Parameters into KeyValuePair<string, string>
        List<KeyValuePair<string, string>>? output = 
            System.Text.Json.JsonSerializer
            .Deserialize<List<KeyValuePair<string, string>>>((string)backgroundOperation["outputparameters"]);

        output.ForEach(x => {
            Console.WriteLine($"\t{x.Key}: {x.Value}");
        });

        Console.WriteLine($"Error Code: {backgroundOperation.GetAttributeValue<string>("errorcode")}");
        Console.WriteLine($"Error Message: {backgroundOperation.GetAttributeValue<string>("errormessage")}");
    }
    // Catch Dataverse errors
    catch (FaultException<OrganizationServiceFault> ex)
    {
        Console.WriteLine($"ErrorCode:{ex.Detail.ErrorCode}");
        Console.WriteLine($"Message:{ex.Detail.Message}");
    }
    // Catch other errors
    catch (Exception error)
    {
        Console.WriteLine($"Some other error occurred: '{error.Message}'");
    }
}

Wartende Ausgabe:

Name: sample_ExportDataUsingFetchXmlToAnnotation
State Code: Locked
Status Code:  In Progress
Output Parameters:  
Error Code:  
Error Message:

Fertige Ausgabe:

Name: sample_ExportDataUsingFetchXmlToAnnotation
State Code: Completed
Status Code:  Succeeded
Output Parameters:
        AnnotationId: {value}
Error Code:  
Error Message:

Fehlerausgabe:

Name: sample_ExportDataUsingFetchXmlToAnnotation
State Code: Completed
Status Code:  Failed
Output Parameters: 
Error Code:  -2147187707
Error Message:  Access is denied.

Wenn die Plattform den Fehler produziert, hat er einen ganzzahligen Wert, der einem der Codes entspricht, die in den Webdienst-Fehlercodes aufgeführt sind. Wenn die Plattform den Fehler nicht auslöst, wird ihr Wert auf Null gesetzt.

Id nicht gefunden:

ErrorCode:-2147185406
Message:The HTTP status code of the response was not expected (404).

Status: 404
Response:
{"error":{"message":"Could not find item '110eaa68-db17-4115-ad74-d185823fc089'.","details":[{"message":"\r\nErrors : [\r\n  \"Resource Not Found. Learn more: https://aka.ms/cosmosdb-tsg-not-found\"\r\n]\r\n"}]}}

Die Statusmonitorressource abrufen

Sie können die Statusmonitor-Ressource mit einer GET-Anfrage abfragen, die den Status des Hintergrundvorgangs zurückgibt. Wenn der Vorgang abgeschlossen ist, stellt er die Ausgabe der benutzerdefinierten API bereit. Wenn während der Ausführung ein Fehler aufgetreten ist, erhalten Sie eine Fehlermeldung und einen Code.

Senden Sie eine Anforderung an die URL der Statusmonitorressource, die mit zurückgegeben wurde der Location-Antwortheader der ursprünglichen Anforderung.

Anforderung:

GET [Organization URI]/api/backgroundoperation/{backgroundoperationid}
Content-Type: application/json

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json

{
  backgroundOperationErrorCode: {INT},
  backgroundOperationErrorMessage: {string},
  backgroundOperationStateCode: {INT},
  backgroundOperationStatusCode: {INT},
  outputParam1: {value},
  outputParam2: {value},
  outputParam3: {value},
}

backgroundOperationErrorCode und backgroundOperationErrorMessage Werte werden nur berücksichtigt, wenn ein Fehler auftritt. Die Ausgabeparameter sind nur enthalten, wenn der Vorgang erfolgreich abgeschlossen wurde.

Labels sind mit der Ressource Status Monitor nicht verfügbar.

Benachrichtigung über Ergebnis empfangen

Um eine Benachrichtigung zu erhalten, wenn ein Vorgang im Hintergrund abgeschlossen ist, können Sie entweder eine Callback-URL in Ihre Anfrage einfügen oder das Ereignis OnBackgroundOperationComplete abonnieren.

Rückruf anfordern

Sie können in Ihrer Anforderung eine URL angeben, um einen Rückruf zu erhalten, wenn der Vorgang abgeschlossen ist. Dataverse verwendet diese URL, um eine POST-Anfrage mit dem folgenden Payload zu senden:

{
    "location": "< status monitor resource URL >",
    "backgroundOperationId": "{GUID}",
    "backgroundOperationStateCode": {INT},
    "backgroundOperationStatusCode": {INT},
    "backgroundOperationErrorCode": {INT},
    "backgroundOperationErrorMessage": {string},
}

backgroundOperationErrorCode und backgroundOperationErrorMessage werden nur im Falle eines Fehlers berücksichtigt.

Die Rufrufnutzdaten enthalten keine Ausgabeparameter. Die Website, die den Rückruf erhält, muss eine authentifizierte GET-Anfrage über die URL der Status Monitor-Ressource senden, um die Ergebnisse zu erhalten.

Wenn die URL eine Authentifizierung erfordert, muss es sich um eine autarke Shared Access Signature (SAS) URL handeln. Es ist nicht möglich, weitere Header zur Aufnahme von API-Schlüsseln oder Token für die Authentifizierung hinzuzufügen.

Vielleicht möchten Sie eine Website wie webhook.site verwenden, um die Rückruf-URL zu testen.

Wie Sie einen Callback anfordern, hängt davon ab, ob Sie das SDK oder die Web-API verwenden. In den folgenden Beispielen wird zu Testzwecken eine Anfrage über einen Webhook an webhook.site gesendet.

Legen Sie mit dem SDK den ExecuteBackgroundOperation.CallbackUri-Parameter an die URL zum Senden der Anforderung fest.

static void SendRequestAsynchronouslyWithCallback(IOrganizationService service)
{
    //Create a request for message defined as a custom API to run in the background
    var asyncRequest = new OrganizationRequest("sample_ExportDataUsingFetchXmlToAnnotation")
    {
        Parameters =
        {
            {"FetchXml",  @"<fetch version='1.0'  
                                    output-format='xml-platform' 
                                    mapping='logical'>
                                <entity name='account'>
                                    <attribute name='accountid'/>
                                    <attribute name='name'/>  
                                </entity>
                            </fetch>" }
        }
    };

    //Create a request to execute the message in the background
    var request = new OrganizationRequest("ExecuteBackgroundOperation")
    {
        Parameters =
        {
            {"Request", asyncRequest },
            // Request a callback
            {"CallbackUri", "https://webhook.site/<id>" }
        }
    };

    //Execute the background operation request
    var response = service.Execute(request);

    Console.WriteLine($"BackgroundOperationId: {response["BackgroundOperationId"]}");
    Console.WriteLine($"Location: {response["Location"]}");
}

Abonnieren Sie das Ereignis OnBackgroundOperationComplete

Eine weitere Möglichkeit, eine Benachrichtigung über den Abschluss eines Vorgangs im Hintergrund zu erhalten, besteht darin, einen Schritt auf die OnBackgroundOperationComplete Nachricht zu registrieren. Diese Nachricht ist eine Custom-API, die nur asynchrone Schrittregistrierungen zulässt. Dies ist ein Beispiel für den Typ von Nachrichten, die mit einer Custom-API erstellt werden, um Geschäftsereignisse darzustellen.

Wie der Name schon sagt, tritt das Ereignis OnBackgroundOperationComplete jedes Mal auf, wenn ein Hintergrundvorgang abgeschlossen ist. Wenn Sie einen asynchronen Schritt für dieses Ereignis registrieren, können Sie jede Art von Logik in einem Plug-in ausführen oder die Daten an Azure Services oder einen Webhook weiterleiten. Erfahren Sie mehr:

Die folgenden Tabellen beschreiben die Eingabe- und Ausgabeparameter für die OnBackgroundOperationComplete-Nachricht.

Eingabeparameter:

Name des Dataflows Type Beschreibung
PayloadType Ganzzahl Welcher Typ von Antwort wird an die Callback-URI gesendet, wenn der Hintergrundvorgang abgeschlossen ist; bei Hintergrundvorgängen immer Null

Dieses Feld ist intern und sollte nicht aktualisiert werden.
LocationUrl String URL des Speicherorts
BackgroundOperationId GUID Die ID des Hintergrundvorgangs

Ausgabeparameter:

Name des Dataflows Type Beschreibung
OperationName String Name des Vorgangs
BackgroundOperationStateCode Ganzzahl Statuscode für den Hintergrundvorgang
BackgroundOperationStatusCode Ganzzahl Statuscode für Hintergrundvorgänge

Konfigurieren Sie die OnBackgroundOperationComplete Nachricht wie in der Anleitung zur Registrierung eines Plug-ins gezeigt. Stellen Sie sicher, dass Sie den Namen der Nachricht auf OnBackgroundOperationComplete setzen. Setzen Sie Auto Delete auf true, damit der Datensatz Systemauftrag (AsyncOperation) automatisch entfernt wird.

Hintergrundvorgänge abbrechen

Sie können einen von Ihnen initiierten Hintergrundvorgang abbrechen, wenn er noch nicht begonnen hat.

  • Wenn der Vorgang nicht gestartet wurde, führt Dataverse ihn nicht aus.
  • Wenn der Vorgang bereits begonnen hat, wird er durch die Dataverse nicht gestoppt.
  • Wenn bei der Ausführung eines von Ihnen abgebrochenen Hintergrundvorgangs ein Fehler auftritt, wird der Vorgang mit Dataverse nicht wiederholt.
  • Wenn der Vorgang bereits abgeschlossen ist, erhalten Sie die folgende Fehlermeldung: Canceling background operation is not allowed after it is in terminal state.

Sie können einen Hintergrundvorgang auf zwei Arten abbrechen:

Abbrechen eines Hintergrundvorgangs durch Aktualisieren von backgroundoperations

Aktualisieren Sie die Zeile in der Tabelle backgroundoperations, um die backgroundoperationstatecode auf 2 (Gesperrt) und backgroundoperationstatuscode auf 22 (Abbrechen) zu setzen.

Wie Sie die backgroundoperations Tabelle aktualisieren, hängt davon ab, ob Sie das SDK oder die Web-API verwenden.

static void CancelBackgroundOperationRequest(
    IOrganizationService service, 
    Guid backgroundOperationId)
{
    var backgroundOperation = new Entity(
        entityName: "backgroundoperation", 
        id: backgroundOperationId)
    { 
        Attributes =
        {
            //Set state as Locked
            {"backgroundoperationstatecode", new OptionSetValue(2) },
            //Set status as Cancelling
            {"backgroundoperationstatuscode", new OptionSetValue(22) }
        }            
    }; 

    service.Update(backgroundOperation);
}

Senden Sie eine DELETE-Anforderung an die Statusmonitorressource

Sie können einen Vorgang im Hintergrund auch abbrechen, indem Sie eine DELETE-Anfrage an die Status Monitor Ressource senden.

Anforderung:

DELETE [Organization URI]/api/backgroundoperation/{backgroundoperationid}

Antwort:

HTTP/1.1 200 Ok

{
    backgroundOperationStateCode: 2,
    backgroundOperationStatusCode: 22
}

Retries

Wenn während der Ausführung der Anforderung ein Fehler auftritt, wird sie bis zu dreimal wiederholt. Diese Wiederholungsversuche verwenden eine exponentielle Backoff-Strategie.