Share via

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

  • Article

[Cet article fait partie de la documentation en version préliminaire et peut faire l’objet de modifications.]

Utilisez des opérations en arrière-plan pour envoyer des requêtes que Dataverse traite de manière asynchrone. Les opérations en arrière-plan sont utiles lorsque vous ne souhaitez pas maintenir une connexion pendant l’exécution d’une demande.

Lorsqu’une opération en arrière-plan se termine, vous pouvez être averti de deux manières :

Vous pouvez récupérer le résultat d’une opération en arrière-plan de deux manières :

Pour exécuter une requête en arrière-plan, l’opération doit être définie en tant qu’API personnalisée. Découvrez comment créer et utiliser des API personnalisées et récupérer des données sur les API personnalisées.

Les API personnalisées utilisent des plug-ins pour effectuer les opérations de données. Comme tous les plug-ins Dataverse, ces plug-ins ont un délai d’exécution de deux minutes. L’envoi de la requête de manière asynchrone ne fournit pas plus de temps d’exécution.

Privilèges requis

Pour effectuer une opération en arrière-plan, l’utilisateur initiateur doit disposer d’un accès en lecture et en écriture à la table backgroundoperations. Attribuez les privilèges prvReadbackgroundoperation et prvWritebackgroundoperation pour accorder cet accès.

Découvrez comment modifier un rôle de sécurité.

Traitement asynchrone des requêtes

Vous pouvez exécuter des requêtes asynchrones en arrière-plan à l’aide du SDK pour .NET ou de l’API web Dataverse.

Les exemples de cet article utilisent une API personnalisée nommée sample_ExportDataUsingFetchXmlToAnnotation. Cette API personnalisée est décrite dans Exemple : API personnalisée ExportDataUsingFetchXmlToAnnotation.

Utilisez le message ExecuteBackgroundOperation.

Le SDK n’a pas de classes de requête et de réponse ExecuteBackgroundOperation. Jusqu’à ce que ces classes soient ajoutées, utilisez les classes de base OrganizationRequest et OrganizationResponse comme décrit dans Utiliser les messages avec le SDK pour .NET.

La table suivante décrit les paramètres entrants pour le message ExecuteBackgroundOperation.

Nom  Type Description
Request OrganizationRequest (Obligatoire) Contient la demande que vous souhaitez traiter de manière asynchrone. Le message Dataverse de la requête doit être implémenté en tant qu’API personnalisée.
CallbackUri string (Facultatif) Dataverse envoie une requête HTTP POST à ​​cette URL lorsque l’opération est terminée.

La table suivante décrit les paramètres sortants pour le message ExecuteBackgroundOperation.

Nom  Type Description
BackgroundOperationId Guid Identifie la ligne du tableau des opérations en arrière-plan que vous pouvez utiliser pour surveiller ou annuler le traitement de votre demande.
Location string Identifie l’URL de la ressource de moniteur d’état que vous pouvez utiliser pour récupérer l’état de votre demande ou pour l’annuler.

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

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

Sortie :

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

En savoir plus sur l’interface IOrganizationService et comment utiliser les messages avec le SDK pour .NET.

Gérer les opérations en arrière-plan

Lorsque vous envoyez une demande à traiter en arrière-plan, la réponse inclut deux valeurs qui représentent différentes méthodes que vous pouvez utiliser pour surveiller ou annuler les opérations en arrière-plan.

L’interrogation de la table des opérations en arrière-plan ou de la ressource du moniteur d’état pour vérifier les demandes est communément appelée interrogation d’état. Nous vous recommandons d’éviter les interrogations excessives, car cela peut affecter négativement les performances. Si nécessaire, nous vous suggérons d’interroger à un intervalle d’une minute ou plus.

Table Opérations en arrière-plan

La table des opérations en arrière-plan contient des informations sur les demandes à traiter de manière asynchrone. Cette table a le nom logique backgroundoperation et le nom de l’ensemble d’entités backgroundoperations. En savoir plus sur l’opération d’arrière-plan EntityType.

La table suivante décrit les colonnes que vous pouvez utiliser pour gérer l’état des opérations en arrière-plan.

Display name
Nom du schéma
Nom logique		 Type Description
Opération en arrière-plan
BackgroundOperationId
backgroundoperationid		 Uniqueidentifier La clé primaire
Status
StateCode
backgroundoperationstatecode		 Picklist État des opérations en arrière-plan

Options :
– Valeur : 0, Étiquette : Prêt
– Valeur : 2, Étiquette : Verrouillé
– Valeur : 3, Étiquette : Terminé
Raison du statut
StatusCode
backgroundoperationstatuscode		 Picklist Statut des opérations en arrière-plan

Options :
– Valeur : 0, Étiquette : En attente de ressources (État : Prêt)
– Valeur : 20, Étiquette : En cours (État : Verrouillé)
– Valeur : 22, Étiquette : Annulation (État : Verrouillé)
– Valeur : 30, Étiquette : Réussi (État : Terminé)
– Valeur : 31, Étiquette : Échec (État : Terminé)
– Valeur : 32, Étiquette : Annulé (État : Terminé)
Nom 
Name
name		 String Le UniqueName de l’API personnalisée utilisée pour l’opération en arrière-plan
Nom d’affichage
DisplayName
displayname		 String Le DisplayName de l’API personnalisée utilisée pour l’opération en arrière-plan
Paramètres d’entrée
InputParameters
inputparameters		 Memo Les paramètres entrants qui ont été fournis pour démarrer l’opération en arrière-plan

Cette chaîne est un tableau sérialisé JSON de Key et Value.
Paramètres de sortie
OutputParameters
outputparameters		 Memo La réponse de l’opération en arrière-plan

Cette chaîne est un tableau sérialisé JSON de Key et Value.
Heure de début
StartTime
starttime		 DateHeure Lorsque l’opération en arrière-plan a lancé l’exécution
Heure de fin
EndTime
endtime		 DateHeure Lorsque l’opération en arrière-plan a arrêté l’exécution
Nombre de nouvelles tentatives
RetryCount
retrycount		 Integer Le nombre de tentatives d’opération en arrière-plan
Code d’erreur
ErrorCode
errorcode		 Integer Le code d’erreur si l’opération en arrière-plan échoue

Si l’erreur provient de Dataverse, elle a une valeur entière qui correspond à l’un des codes répertoriés dans les codes d’erreur du service Web. Si l’erreur ne vient pas de Dataverse, la valeur est mise à zéro.
Message d\’erreur
ErrorMessage
errormessage		 Memo Le message d’erreur si l’opération en arrière-plan échoue
Exécuter en tant que
RunAs
runas		 String systemuserid du systemuser utilisé pour exécuter l’opération en arrière-plan
Date de création
CreatedOn
createdon		 DateHeure Lorsque l’enregistrement a été créé
Durée de vie
TTLInSeconds
ttlinseconds		 Integer Durée de vie en secondes, après quoi l’enregistrement est automatiquement supprimé ; la valeur par défaut est de 90 jours

Interroger la table des opérations en arrière-plan

Assurez-vous d’inclure ces colonnes dans votre requête :

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

La façon dont vous interrogez la table dépend de si vous utilisez le SDK ou l’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 terminée :

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 plate-forme produit l’erreur, elle a une valeur entière qui correspond à l’un des codes répertoriés dans les codes d’erreur des services Web. Si la plate-forme ne génère pas d’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"}]}}

Interroger la ressource de l’écran d’état

Vous pouvez interroger la ressource de moniteur d’état avec une requête GET, qui renvoie l’état de l’opération en arrière-plan. Si l’opération est terminée, elle fournit la sortie de l’API personnalisée. Si une erreur s’est produite lors de l’exécution, vous recevez un message d’erreur et un code.

Envoyez une demande à l’URL de la ressource de moniteur d’état qui a été renvoyée avec l’en-tête de réponse Location de la requête d’origine.

Demande :

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

Réponse :

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

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

Les valeurs backgroundOperationErrorCode et backgroundOperationErrorMessage sont incluses uniquement lorsqu’une erreur se produit. Les paramètres sortants sont inclus uniquement lorsque l’opération se termine avec succès.

Les étiquettes ne sont pas disponibles avec la ressource de moniteur d’état.

Recevoir la notification du résultat

Pour recevoir une notification lorsqu’une opération en arrière-plan se termine, vous pouvez soit inclure une URL de rappel avec votre demande ou vous abonner à l’événement OnBackgroundOperationComplete.

Demander un rappel

Vous pouvez spécifier une URL dans votre demande pour recevoir un rappel lorsque l’opération est terminée. Dataverse utilise cette URL pour envoyer une requête POST avec la charge utile suivante :

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

Les valeurs backgroundOperationErrorCode et backgroundOperationErrorMessage sont incluses uniquement lorsqu’une erreur se produit.

La charge utile de rappel n’inclut aucun paramètre de sortie. Le site qui reçoit le rappel doit envoyer une demande GET authentifiée à l’aide de l’URL de la ressource de moniteur d’état pour obtenir des résultats.

Si l’URL nécessite une authentification, il doit s’agir d’une URL de signature d’accès partagé (SAS) autosuffisante. Il n’est pas possible d’inclure d’autres en-têtes pour inclure des clés d’API ou des jetons pour l’authentification.

Vous voudrez peut-être utiliser un site comme webhook.site pour tester l’URL de rappel.

La façon dont vous demandez un rappel dépend de si vous utilisez le SDK ou l’API Web. Les exemples suivants envoient une requête à l’aide d’un webhook à webhook.site pour les tests.

Avec le SDK, définissez le paramètre ExecuteBackgroundOperation.CallbackUri à 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 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"]}");
}

Abonnez-vous à l’événement OnBackgroundOperationComplete

Une autre façon de recevoir une notification lorsqu’une opération en arrière-plan est terminée consiste à enregistrer une étape sur le message OnBackgroundOperationComplete. Ce message est une API personnalisée qui autorise uniquement les enregistrements d’étapes asynchrones. Il s’agit d’un exemple du type de messages créés à l’aide d’une API personnalisée pour représenter des événements commerciaux.

Comme son nom l’indique, l’événement OnBackgroundOperationComplete se produit chaque fois qu’une opération en arrière-plan se termine. Lorsque vous enregistrez une étape asynchrone sur cet événement, vous pouvez exécuter n’importe quel type de logique dans un plug-in ou transférer les données vers les services Azure ou un webhook. En savoir plus :

Les tables suivantes décrivent les paramètres entrants et sortants pour le message OnBackgroundOperationComplete.

Paramètres d’entrée :

Nom  Type Description
PayloadType Integer Quel type de réponse est envoyé à l’URI de rappel lorsque l’opération en arrière-plan est terminée ? toujours zéro pour les opérations en arrière-plan

Ce champ est interne et ne doit pas être mis à jour.
LocationUrl String URL d’emplacement
BackgroundOperationId Guid ID d’opération de l’arrière-plan

Paramètres sortants :

Nom  Type Description
OperationName String Nom de l’opération
BackgroundOperationStateCode Integer Code d’état des opérations en arrière-plan
BackgroundOperationStatusCode Integer Code de statut des opérations en arrière-plan

Configurez le message OnBackgroundOperationComplete comme indiqué dans les instructions pour enregistrer un plug-in. Assurez-vous de définir le nom du message sur OnBackgroundOperationComplete. Définissez Suppression automatique sur true afin que l’enregistrement Tâche système (AsyncOperation) soit automatiquement supprimé.

Annuler les opérations en arrière-plan

Vous pouvez annuler une opération en arrière-plan que vous avez lancée si elle n’a pas démarré.

  • Si l’opération n’a pas démarré, Dataverse ne l’exécute pas.
  • Si l’opération a démarré, Dataverse ne l’arrête pas.
  • Si une erreur se produit lors de l’exécution d’une opération en arrière-plan que vous avez annulée, Dataverse ne la réessaye pas.
  • Si l’opération est déjà terminée, vous obtenez l’erreur suivante : Canceling background operation is not allowed after it is in terminal state.

Vous pouvez annuler une opération en arrière-plan de deux manières :

Annuler une opération en arrière-plan en mettant à jour backgroundoperations

Mettez à jour la ligne dans la table backgroundoperations pour définir le backgroundoperationstatecode sur 2 (Verrouillé) et backgroundoperationstatuscode sur 22 (Annulation).

La façon dont vous mettez à jour la table backgroundoperations dépend de si vous utilisez le SDK ou l’API Web.

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

Envoyer une requête DELETE à la ressource de moniteur d’état

Vous pouvez également annuler une opération en arrière-plan en envoyant une requête DELETE à la ressource de moniteur d’état.

Demande :

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

Réponse :

HTTP/1.1 200 Ok

{
    backgroundOperationStateCode: 2,
    backgroundOperationStatusCode: 22
}

Nouvelles tentatives

Si une erreur se produit lors de l’exécution de la requête, elle est réessayée jusqu’à trois fois. Ces nouvelles tentatives utilisent une stratégie d’interruption exponentielle.