Partager via

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

[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 recevoir une notification de deux façons :

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

Pour exécuter une requête en arrière-plan, définissez l’opération en tant qu’API personnalisée. Pour plus d’informations, consultez 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 des 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 asynchrone de la requête ne fournit pas plus de temps d’exécution.

Privilèges requis

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

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

Demande de traitement asynchrone

Vous pouvez exécuter des requêtes asynchrones en arrière-plan à l’aide du Kit de développement logiciel (SDK) pour .NET ou de l’API Web Dataverse.

Les exemples de cet article utilisent une API personnalisée nommée sample_ExportDataUsingFetchXmlToAnnotation. Pour plus d’informations sur cette API personnalisée, consultez Sample : ExportDataUsingFetchXmlToAnnotation custom API.

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.

Nom Type Descriptif
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 ficelle (Facultatif) Dataverse envoie une requête POST HTTP à cette URL lorsque l’opération est terminée.

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

Nom Type Descriptif
BackgroundOperationId GUID Identifie la ligne de table d’opérations en arrière-plan que vous pouvez utiliser pour surveiller ou annuler le traitement de votre demande.
Location ficelle Identifie l’URL de ressource du 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 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.

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 des opérations en arrière-plan.

L’interrogation de la table des opérations en arrière-plan ou de la ressource de surveillance de l'état pour vérifier les demandes est communément appelée sondage d'état. Évitez les sondages excessifs, car ils peuvent affecter négativement les performances. Si nécessaire, interrogez à un intervalle d’une minute ou plus.

Tableau des 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 porte le nom backgroundoperation logique et le nom backgroundoperationsdu jeu d’entités. Découvrez le type d'entité de l'opération en arrière-plan.

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

Nom complet
Nom du schéma
Nom logique		 Type Descriptif
Opération en arrière-plan
BackgroundOperationId
backgroundoperationid		 Uniqueidentifier La clé primaire
Statut
StateCode
backgroundoperationstatecode		 Liste déroulante État de l’opération en arrière-plan

Options :
- Valeur : 0, Étiquette : Prêt
- Valeur : 2, Étiquette : Verrouillé
- Valeur : 3, Étiquette : Terminé
Raison du statut
StatusCode
backgroundoperationstatuscode		 Liste déroulante État de l’opération en arrière-plan

Options :
- Valeur : 0, Étiquette : En attente de ressources (State :Ready)
- Valeur : 20, Étiquette : en cours (State :Locked)
- Valeur : 22, Étiquette : Annulation (State :Locked)
- Valeur : 30, Étiquette : Réussi (État :Terminé)
- Valeur : 31, Étiquette : Échec (État :Terminé)
- Valeur : 32, Étiquette : Annulé (État :Terminé)
Nom
Name
name		 Chaîne L’API UniqueName personnalisée utilisée pour l’opération en arrière-plan
DisplayName
DisplayName
displayname		 Chaîne L’API DisplayName personnalisée utilisée pour l’opération en arrière-plan
Paramètres d’entrée
InputParameters
inputparameters		 Memo Paramètres d’entrée 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		 Date et heure Lorsque le processus en arrière-plan a commencé l’exécution
Heure de fin
EndTime
endtime		 Date et heure Lorsque l’opération en arrière-plan s'est terminée
Nombre de nouvelles tentatives
RetryCount
retrycount		 Nombre entier Nombre de fois où l’opération en arrière-plan a été retentée
Code d’erreur
ErrorCode
errorcode		 Nombre entier 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 provient pas de Dataverse, la valeur est définie sur zéro.
Message d'erreur
ErrorMessage
errormessage		 Memo Message d’erreur si l’opération en arrière-plan échoue
Exécuter en tant que
RunAs
runas		 Chaîne systemuserid du systemuser utilisé pour exécuter l’opération en arrière-plan
Création le
CreatedOn
createdon		 Date et heure Lors de la création de l’enregistrement
Durée de vie
TTLInSeconds
ttlinseconds		 Nombre entier Durée de vie en secondes, après laquelle l’enregistrement est automatiquement supprimé ; la valeur par défaut est de 90 jours

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

Veillez à inclure ces colonnes dans votre requête :

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

La façon dont vous interrogez la table dépend de l’utilisation du Kit de développement logiciel (SDK) ou de 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 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, définissez sa valeur 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 du moniteur d’état à l’aide d’une requête GET. Cette requête 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 se produit pendant l’exécution, vous recevez un message d’erreur et un code.

Envoyez une demande à l’URL de ressource du moniteur d’état retournée par la requête d’origine dans l’en-tête Location de réponse.

Requête :

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

La réponse inclut les valeurs backgroundOperationErrorCode et backgroundOperationErrorMessage uniquement lorsqu’une erreur se produit. Il inclut des paramètres de sortie uniquement lorsque l’opération se termine correctement.

La ressource du moniteur d’état ne fournit pas d’étiquettes.

Recevoir une notification de résultat

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

Demander un rappel

Vous pouvez spécifier une URL dans votre demande pour recevoir un rappel à la fin de l’opération. 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},
}

backgroundOperationErrorCode et backgroundOperationErrorMessage sont inclus 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 requête GET authentifiée à l’aide de l’URL de ressource du moniteur d’état pour obtenir les résultats.

Si l’URL nécessite une authentification, il doit s’agir d’une URL de signature d’accès partagé autonome (SAP ). Vous ne pouvez pas inclure d’en-têtes supplémentaires pour inclure des clés d’API ou des jetons pour l’authentification.

Pour tester l’URL de rappel, envisagez d’utiliser un site comme webhook.site.

La façon dont vous demandez un rappel dépend de l’utilisation du Kit de développement logiciel (SDK) ou de l’API web. Les exemples suivants envoient une requête à l’aide d’un webhook pour webhook.site à des fins de test.

À l’aide du 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"]}");
}

S’abonner à l’événement OnBackgroundOperationComplete

Vous pouvez recevoir une notification lorsqu’une opération en arrière-plan se termine en inscrivant une étape sur le OnBackgroundOperationComplete message. Ce message est une API personnalisée qui prend uniquement en charge les inscriptions 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 métier.

Comme le suggère le nom, l’événement OnBackgroundOperationComplete se produit chaque fois qu’une opération en arrière-plan se termine. Lorsque vous inscrivez une étape asynchrone sur cet événement, vous pouvez effectuer n’importe quel type de logique souhaité dans un plug-in ou transférer les données vers les services Azure ou un webhook. Pour plus d’informations, consultez :

Les tableaux suivants décrivent les paramètres d’entrée et de sortie du OnBackgroundOperationComplete message.

Paramètres d’entrée :

Nom Type Descriptif
PayloadType Nombre entier Type de réponse envoyé à l’URI de rappel lorsque l’opération en arrière-plan se termine. Toujours zéro pour les opérations en arrière-plan.

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

Paramètres de sortie :

Nom Type Descriptif
OperationName Chaîne Nom de l’opération
BackgroundOperationStateCode Nombre entier Code d’état de l’opération en arrière-plan
BackgroundOperationStatusCode Nombre entier Code d’état de l’opération en arrière-plan

Configurez le OnBackgroundOperationComplete message comme indiqué dans les instructions pour inscrire un plug-in. Définissez le nom du message sur OnBackgroundOperationComplete. Définissez la suppressiontrue automatique pour que l’enregistrement de travail 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 pendant l’exécution d’une opération en arrière-plan que vous avez annulée, Dataverse ne le 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 façons :

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

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

La façon dont vous mettez à jour la backgroundoperations table dépend de l’utilisation du Kit de développement logiciel (SDK) ou de 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 demande DELETE à la ressource du moniteur d’état.

Requête :

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

Réponse:

HTTP/1.1 200 Ok

{
    backgroundOperationStateCode: 2,
    backgroundOperationStatusCode: 22
}

Nouvelle tentatives

Si une erreur se produit pendant l’exécution de la requête, le système effectue une nouvelle tentative jusqu’à trois fois. Ces nouvelles tentatives utilisent une stratégie de repli exponentiel.

  • Last updated on