Utiliser du code personnalisé dans un connecteur personnalisé

Le code personnalisé transforme les charges utiles des demandes et des réponses au-delà de la portée des modèles de stratégie existants. Lorsque vous utilisez du code, il est prioritaire sur la définition sans code.

Pour en savoir plus, consultez Créer un connecteur personnalisé à partir de zéro.

Classe de script

Votre code doit implémenter une méthode appelée ExecuteAsync, qui s’exécute pendant l’exécution. Vous pouvez créer d’autres méthodes dans cette classe en fonction des besoins et les appeler à partir de la ExecuteAsync méthode. Le nom de la classe doit être Script et il doit implémenter ScriptBase.

public class Script : ScriptBase
{
    public override Task<HttpResponseMessage> ExecuteAsync()
    {
        // Your code here
    }
}

Définition des classes et interfaces de support

La Script classe fait référence aux classes et interfaces suivantes. Utilisez-les pour les tests et la compilation locaux.

public abstract class ScriptBase
{
    // Context object
    public IScriptContext Context { get; }

    // CancellationToken for the execution
    public CancellationToken CancellationToken { get; }

    // Helper: Creates a StringContent object from the serialized JSON
    public static StringContent CreateJsonContent(string serializedJson);

    // Abstract method for your code
    public abstract Task<HttpResponseMessage> ExecuteAsync();
}

public interface IScriptContext
{
    // Correlation Id
    string CorrelationId { get; }

    // Connector Operation Id
    string OperationId { get; }

    // Incoming request
    HttpRequestMessage Request { get; }

    // Logger instance
    ILogger Logger { get; }

    // Used to send an HTTP request
    // Use this method to send requests instead of HttpClient.SendAsync
    Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request,
        CancellationToken cancellationToken);
}

Exemples

script « Hello World »

Cet exemple de script retourne toujours Hello World comme réponse pour toutes les requêtes.

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    // Create a new response
    var response = new HttpResponseMessage();

    // Set the content
    // Initialize a new JObject and call .ToString() to get the serialized JSON
    response.Content = CreateJsonContent(new JObject
    {
        ["greeting"] = "Hello World!",
    }.ToString());

    return response;
}

Script d’expression régulière

L’exemple suivant prend du texte à mettre en correspondance et l’expression regex, puis retourne le résultat de la correspondance dans la réponse.

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    // Check if the operation ID matches what is specified in the OpenAPI definition of the connector
    if (this.Context.OperationId == "RegexIsMatch")
    {
        return await this.HandleRegexIsMatchOperation().ConfigureAwait(false);
    }

    // Handle an invalid operation ID
    HttpResponseMessage response = new HttpResponseMessage(HttpStatusCode.BadRequest);
    response.Content = CreateJsonContent($"Unknown operation ID '{this.Context.OperationId}'");
    return response;
}

private async Task<HttpResponseMessage> HandleRegexIsMatchOperation()
{
    HttpResponseMessage response;

    // We assume the body of the incoming request looks like this:
    // {
    //   "textToCheck": "<some text>",
    //   "regex": "<some regex pattern>"
    // }
    var contentAsString = await this.Context.Request.Content.ReadAsStringAsync().ConfigureAwait(false);

    // Parse as JSON object
    var contentAsJson = JObject.Parse(contentAsString);

    // Get the value of text to check
    var textToCheck = (string)contentAsJson["textToCheck"];

    // Create a regex based on the request content
    var regexInput = (string)contentAsJson["regex"];
    var rx = new Regex(regexInput);

    JObject output = new JObject
    {
        ["textToCheck"] = textToCheck,
        ["isMatch"] = rx.IsMatch(textToCheck),
    };

    response = new HttpResponseMessage(HttpStatusCode.OK);
    response.Content = CreateJsonContent(output.ToString());
    return response;
}

Script de redirection

L’exemple suivant transfère la demande entrante au backend.

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    // Check if the operation ID matches what is specified in the OpenAPI definition of the connector
    if (this.Context.OperationId == "ForwardAsPostRequest")
    {
        return await this.HandleForwardOperation().ConfigureAwait(false);
    }

    // Handle an invalid operation ID
    HttpResponseMessage response = new HttpResponseMessage(HttpStatusCode.BadRequest);
    response.Content = CreateJsonContent($"Unknown operation ID '{this.Context.OperationId}'");
    return response;
}

private async Task<HttpResponseMessage> HandleForwardOperation()
{
    // Example case: If your OpenAPI definition defines the operation as 'GET', but the backend API expects a 'POST',
    // use this script to change the HTTP method.
    this.Context.Request.Method = HttpMethod.Post;

    // Use the context to forward/send an HTTP request
    HttpResponseMessage response = await this.Context.SendAsync(this.Context.Request, this.CancellationToken).ConfigureAwait(continueOnCapturedContext: false);
    return response;
}

Script de transfert et de transformation

L’exemple suivant transfère la demande entrante et transforme la réponse renvoyée par le backend.

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    // Check if the operation ID matches what is specified in the OpenAPI definition of the connector
    if (this.Context.OperationId == "ForwardAndTransformRequest")
    {
        return await this.HandleForwardAndTransformOperation().ConfigureAwait(false);
    }

    // Handle an invalid operation ID
    HttpResponseMessage response = new HttpResponseMessage(HttpStatusCode.BadRequest);
    response.Content = CreateJsonContent($"Unknown operation ID '{this.Context.OperationId}'");
    return response;
}

private async Task<HttpResponseMessage> HandleForwardAndTransformOperation()
{
    // Use the context to forward/send an HTTP request
    HttpResponseMessage response = await this.Context.SendAsync(this.Context.Request, this.CancellationToken).ConfigureAwait(continueOnCapturedContext: false);

    // Do the transformation if the response was successful, otherwise return error responses as-is
    if (response.IsSuccessStatusCode)
    {
        var responseString = await response.Content.ReadAsStringAsync().ConfigureAwait(continueOnCapturedContext: false);
        
        // Example case: response string is some JSON object
        var result = JObject.Parse(responseString);
        
        // Wrap the original JSON object into a new JSON object with just one key ('wrapped')
        var newResult = new JObject
        {
            ["wrapped"] = result,
        };
        
        response.Content = CreateJsonContent(newResult.ToString());
    }

    return response;
}

Espaces de noms pris en charge

Tous les espaces de noms C# ne sont pas pris en charge. Actuellement, vous pouvez utiliser les fonctions des espaces de noms suivants uniquement.

Important

La version .NET actuellement prise en charge est .NET Standard 2.0.

using System;
using System.Collections;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.IO.Compression;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Security;
using System.Security.Authentication;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using System.Web;
using System.Xml;
using System.Xml.Linq;
using System.Drawing;
using System.Drawing.Drawing2D;
using System.Drawing.Imaging;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

Exemples GitHub

Pour consulter des exemples dans le connecteur DocuSign, accédez à Connecteurs Power Platform dans GitHub.

FAQ sur le code personnalisé

Pour en savoir plus sur le code personnalisé, consultez l’étape 4 : (Facultatif) Utiliser la prise en charge du code personnalisé.

Q : Puis-je utiliser plusieurs scripts par connecteur personnalisé ?R : Non, vous ne pouvez utiliser qu’un seul fichier de script par connecteur personnalisé.

Q : J’obtiens une erreur de serveur interne lors de la mise à jour de mon connecteur personnalisé. Quel pourrait être le problème ? R : Il y a probablement un problème lors de la compilation de votre code. À l’avenir, le système affiche la liste complète des erreurs de compilation pour améliorer cette expérience. Pour l’instant, utilisez les classes de prise en charge pour tester les erreurs de compilation localement comme solution de contournement.

Q : Puis-je ajouter la journalisation à mon code et obtenir une trace pour le débogage ?R : Pas actuellement, mais la prise en charge de cette fonctionnalité sera ajoutée à l’avenir.

Q : Comment puis-je tester mon code en attendant ?R : Testez-le localement et vérifiez que vous pouvez compiler du code à l’aide uniquement des espaces de noms fournis dans les espaces de noms pris en charge. Pour plus d’informations sur les tests locaux, consultez Écrire du code dans un connecteur personnalisé.

Q : Existe-t-il des limites ?R : Oui. Votre script doit terminer l’exécution dans les 2 minutes et la taille de votre fichier de script ne peut pas dépasser 1 Mo. Ce nouveau délai d’expiration de 2 minutes s’applique aux connecteurs personnalisés nouvellement créés. Pour les connecteurs personnalisés existants, vous devez mettre à jour le connecteur pour appliquer le nouveau délai d’expiration.

Q : Puis-je créer mon propre client HTTP dans le code de script ?R : Actuellement, oui, mais le système bloque cette fonctionnalité à l’avenir. La méthode recommandée consiste à utiliser la méthode this.Context.SendAsync.

Q : Puis-je utiliser du code personnalisé avec la passerelle de données locale ?R : Pas pour le moment, non.

Prise en charge du réseau virtuel

Lorsque vous utilisez le connecteur dans un environnement Power Platform lié à un réseau virtuel, les limitations suivantes s’appliquent :

  • Context.SendAsync utilise un point de terminaison public, de sorte qu’il ne peut pas accéder aux données à partir de points de terminaison privés sur le réseau virtuel.

Problèmes généraux connus et limitations

Dans certaines régions, l’en-tête OperationId retourne au format codé en base64. Si votre implémentation nécessite la valeur, décodez-la OperationId en base64 pour une utilisation.

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    string realOperationId = this.Context.OperationId;
    // Resolve potential issue with base64 encoding of the OperationId
    // Test and decode if it's base64 encoded
    try {
        byte[] data = Convert.FromBase64String(this.Context.OperationId);
        realOperationId = System.Text.Encoding.UTF8.GetString(data);
    }
    catch (FormatException ex) {}
    // Check if the operation ID matches what is specified in the OpenAPI definition of the connector
    if (realOperationId == "RegexIsMatch")
    // Refer to the original examples above for remaining details
}

Étape suivante

Créer un connecteur personnalisé à partir de zéro

Fournir des commentaires

Nous apprécions grandement les commentaires sur les problèmes liés à notre plate-forme de connecteurs ou les idées de nouvelles fonctionnalités. Pour fournir des commentaires, accédez à Soumettre des problèmes ou obtenir de l’aide avec les connecteurs et sélectionnez votre type de commentaire.