Vorgänge im Hintergrund (Vorschauversion)

Verwenden Sie die ExecuteBackgroundOperation Nachricht.

Das SDK verfügt nicht über ExecuteBackgroundOperation Anforderungs- und Antwortklassen. Verwenden Sie bis zum Hinzufügen dieser Klassen die Basisklassen "OrganizationRequest " und "OrganizationResponse ", wie unter "Verwenden von Nachrichten mit dem SDK für .NET" beschrieben.

In der folgenden Tabelle werden die Eingabeparameter für die ExecuteBackgroundOperation Nachricht beschrieben.

In der folgenden Tabelle werden die Ausgabeparameter für die ExecuteBackgroundOperation Nachricht beschrieben.

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>
                                <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 die Verwendung von Nachrichten mit dem SDK für .NET.

Senden Sie Ihre Anforderung mit der Prefer: respond-async Kopfzeile. Weitere Informationen zu Prefer Kopfzeilen.

Anforderung:

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

{
    "FetchXml": "<fetch>
                    <entity name='account'>
                        <attribute name='accountid'/>
                        <attribute name='name'/>  
                    </entity>
                </fetch>"
}

Antwort:

HTTP/1.1 202 Accepted
Location: [Organization URI]/api/backgroundoperation/<backgroundoperationid value>
x-ms-dyn-backgroundoperationid: <backgroundoperationid value>
Preference-Applied: respond-async

• Der Wert des x-ms-dyn-backgroundoperationid Antwortheaders ist die ID für die Hintergrundvorgangszeile für die Anforderung.
• Der Header der Antwort Location enthält eine URL, die die Ressource des Status Monitors darstellt.

Erfahren Sie, wie Sie Web-API-Aktionen 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:  

Vollständige 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 erzeugt, weist sie einen ganzzahligen Wert auf, der einem der codes entspricht, die in den Webdienstfehlercodes aufgeführt sind. Wenn die Plattform den Fehler nicht erzeugt, wird der Wert auf Null festgelegt.

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

Anforderung:

GET [Organization URI]/api/data/v9.2/backgroundoperations(<backgroundoperationid value>)?$select=
name,
backgroundoperationstatecode,
backgroundoperationstatuscode,
outputparameters,
errorcode,
errormessage
Content-Type: application/json
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Preference-Applied: odata.include-annotations="OData.Community.Display.V1.FormattedValue"

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#backgroundoperations(backgroundoperationstatecode,backgroundoperationstatuscode,outputparameters,errorcode,errormessage)/$entity",
    "@odata.etag": "W/\"92030eaa-0000-0200-0000-644d7c300000\"",
    "backgroundoperationstatecode@OData.Community.Display.V1.FormattedValue": "Completed",
    "backgroundoperationstatecode": 3,
    "backgroundoperationstatuscode@OData.Community.Display.V1.FormattedValue": "Succeeded",
    "backgroundoperationstatuscode": 30,
    "name":"sample_ExportDataUsingFetchXmlToAnnotation"
    "outputparameters": "[{\"Key\":\"AnnotationId\",\"Value\":\"bb26025c-cbe6-ed11-a7c6-000d3a9933c9\"}]",
    "errorcode": null,
    "errormessage": null,
    "backgroundoperationid": "<backgroundoperationid value>",
    "versionnumber": 638183964640916096
}

Legen Sie mit dem SDK den ExecuteBackgroundOperation.CallbackUri Parameter auf die URL fest, um die Anforderung zu senden.

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

Legen Sie mit der Web-API den Anforderungsheader Prefer mit diesem Wert fest: Prefer: respond-async, odata.callback; url="<url>"

Anforderung:

POST [Organization URI]/api/data/v9.2/sample_ExportDataUsingFetchXmlToAnnotation 
Content-Type: application/json
Accept: application/json
Prefer: respond-async, odata.callback; url="https://webhook.site/<id>"

{
    "FetchXml": "<fetch>
                    <entity name='account'>
                        <attribute name='accountid'/>
                        <attribute name='name'/>  
                    </entity>
                </fetch>"
}

Antwort:

HTTP/1.1 202 Accepted
Preference-Applied: callback
x-ms-dyn-backgroundoperationid: <backgroundoperationid value>
location: [Organization URI]/api/backgroundoperation/<backgroundoperationid value>

{
   backgroundOperationId: <backgroundoperationid value>,
   location: [Organization URI]/api/backgroundoperation/<backgroundoperationid value>
}

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

Anforderung:

PATCH [Organization URI]/api/data/v9.2/backgroundoperations(<backgroundoperationid value>) HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
If-Match: *
Content-Type: application/json

{
    "backgroundoperationstatecode": 2,
    "backgroundoperationstatuscode": 22
}

Antwort:

HTTP/1.1 204 No Content
OData-Version: 4.0