Aangepaste code gebruiken in een aangepaste connector

Aangepaste code transformeert payloads voor aanvragen en antwoorden buiten het bereik van bestaande beleidssjablonen. Wanneer u code gebruikt, heeft deze voorrang op de definitie zonder code.

Zie Een volledig nieuwe aangepaste connector maken voor meer informatie.

Script-klasse

Uw code moet een methode implementeren die wordt aangeroepen ExecuteAsync, die tijdens runtime wordt uitgevoerd. U kunt indien nodig andere methoden in deze klasse maken en deze aanroepen vanuit de ExecuteAsync methode. De klassenaam moet Script zijn en moet ScriptBase implementeren.

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

Definitie van ondersteunende klassen en interfaces

De Script klasse verwijst naar de volgende klassen en interfaces. Gebruik ze voor lokale tests en compilatie.

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

Voorbeelden

Hallo Wereld-script

Dit voorbeeldscript retourneert altijd Hallo wereld als antwoord voor alle aanvragen.

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

Regex-script

In het volgende voorbeeld wordt een stuk tekst en een reguliere expressie als invoer gebruikt, waarna het resultaat van de vergelijking in het antwoord wordt weergegeven.

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

Doorstuurscript

In het volgende voorbeeld wordt de binnenkomende aanvraag doorgestuurd naar de back-end.

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 voor doorsturen en transformeren

In het volgende voorbeeld wordt de binnenkomende aanvraag doorgestuurd en wordt de respons van de back-end getransformeerd.

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

Ondersteunde naamruimten

Niet alle C#-naamruimten worden ondersteund. Momenteel kunt u alleen functies uit de volgende naamruimten gebruiken.

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;

GitHub-voorbeelden

Voor voorbeelden in de DocuSign connector, ga naar Power Platform Connectors in GitHub.

Veelgestelde vragen over aangepaste code

Zie stap 4: (Optioneel) Aangepaste codeondersteuning gebruiken voor meer informatie over aangepaste code.

V: Kan ik meerdere scripts per aangepaste connector gebruiken?A: Nee, u kunt slechts één scriptbestand per aangepaste connector gebruiken.

V: Ik krijg een interne serverfout bij het bijwerken van mijn aangepaste connector. Wat zou het probleem kunnen zijn? A: Waarschijnlijk is er een probleem met het compileren van uw code. In de toekomst wordt in het systeem de volledige lijst met compilatiefouten weergegeven om deze ervaring te verbeteren. Gebruik voorlopig de ondersteunende klassen om compilatiefouten lokaal te testen als tijdelijke oplossing.

V: Kan ik logboekregistratie toevoegen aan mijn code en een tracering ophalen voor foutopsporing?A: Momenteel niet, maar de ondersteuning voor deze functie wordt in de toekomst toegevoegd.

V: Hoe kan ik mijn code ondertussen testen?A: Test deze lokaal en zorg ervoor dat u code kunt compileren met behulp van alleen de naamruimten die zijn opgegeven in ondersteunde naamruimten. Zie Code schrijven in een aangepaste connector voor meer informatie over lokaal testen.

V: Zijn er limieten?A: Ja. Uw script moet binnen 2 minuten volledig zijn uitgevoerd en de grootte van uw scriptbestand mag niet groter zijn dan 1 MB. Deze nieuwe time-out van 2 minuten is van toepassing op nieuwe aangepaste connectors. Voor bestaande aangepaste connectors moet u de connector bijwerken om de nieuwe time-out toe te passen.

V: Kan ik mijn eigen HTTP-client maken in scriptcode?A: Op dit moment, ja, maar het systeem blokkeert deze functie in de toekomst. De aanbevolen manier is om de methode this.Context.SendAsync te gebruiken.

V: Kan ik aangepaste code gebruiken met de lokale gegevensgateway?A: Nee, momenteel niet.

Virtual Network-ondersteuning

Wanneer u de connector gebruikt in een Power Platform-omgeving die is gekoppeld aan een virtueel netwerk, gelden de volgende beperkingen:

• Context.SendAsync maakt gebruik van een openbaar eindpunt, zodat het geen toegang heeft tot gegevens van privé-eindpunten in het virtuele netwerk.

Algemene bekende problemen en beperkingen

In sommige regio's wordt de OperationId-header in Base64-gecodeerde indeling geretourneerd. Als voor uw implementatie de OperationId waarde is vereist, decodert base64 deze voor gebruik.

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
}

Volgende stap

Maak een aangepaste connector vanaf nul

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Als u feedback wilt geven, gaat u naar Problemen indienen of hulp krijgen met connectoren en selecteert u het type feedback.