Opérations en arrière-plan (version préliminaire)

Utilisez le message ExecuteBackgroundOperation.

Le Kit de développement logiciel (SDK) n’a ExecuteBackgroundOperation pas de classes de demande et de réponse. Tant que ces classes n’ont pas été ajoutées, utilisez les classes OrganizationRequest et OrganizationResponse de base, comme décrit dans Utiliser les messages avec le Kit de développement logiciel (SDK) pour .NET.

Le tableau suivant décrit les paramètres d’entrée du ExecuteBackgroundOperation message.

Le tableau suivant décrit les paramètres de sortie du ExecuteBackgroundOperation message.

La méthode statique suivante utilise ExecuteBackgroundOperation avec l’API sample_ExportDataUsingFetchXmlToAnnotation personnalisée.

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

sortie :

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

En savoir plus sur l’interface IOrganizationService et sur l’utilisation des messages avec le KIT SDK pour .NET.

Envoyez votre demande avec l’en-tête Prefer: respond-async . En savoir plus sur les en-têtes Prefer.

Requête :

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

Réponse:

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

• La valeur de l’en-tête de réponse x-ms-dyn-backgroundoperationid correspond à l’ID de la ligne d’opération en arrière-plan relative à la requête.
• L’en-tête Location de la réponse contient une URL qui représente la ressource de moniteur d’état.

Découvrez comment utiliser des actions d’API web.

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

Sortie en attente :

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

Sortie complète :

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

Sortie d’erreur :

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

Si la plateforme génère l’erreur, elle a une valeur entière qui correspond à l’un des codes répertoriés dans les codes d’erreur du service Web. Si la plateforme ne produit pas l’erreur, sa valeur est définie sur zéro.

ID introuvable :

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

Requête :

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"

Réponse:

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
}

Avec le Kit de développement logiciel (SDK), définissez le ExecuteBackgroundOperation.CallbackUri paramètre sur l’URL pour envoyer la requête.

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

Avec l’API web, définissez l’en-tête Prefer de requête avec cette valeur : Prefer: respond-async, odata.callback; url="<url>"

Requête :

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

Réponse:

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

Requête :

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
}

Réponse:

HTTP/1.1 204 No Content
OData-Version: 4.0