Написание кода в пользовательском соединителе

Статья
03/07/2025

Пользовательский код преобразует полезные данные запросов и ответов, выходящие за рамки существующих шаблонов политик. Когда используется код, он имеет приоритет над определением без кода.

Для получения дополнительной информации перейдите по ссылке Создание пользовательского коннектора с нуля.

Класс скрипта

В вашем коде должен быть реализован метод ExecuteAsync, который вызывается во время выполнения. При необходимости вы можете создавать другие методы в этом классе и вызывать их из метода ExecuteAsync. Имя класса должно быть Script , и он должен реализовывать ScriptBase.

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

Определение вспомогательных классов и интерфейсов

На следующие классы и интерфейсы ссылается класс "Сценарий". Их можно использовать для локального тестирования и компиляции.

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

Примеры

Сценарий Hello World

Этот пример сценария всегда возвращает Hello World в качестве ответа на все запросы.

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

Сценарий регулярных выражений

В следующем примере берется некоторый текст для сопоставления и регулярное выражение и возвращается результат сопоставления в ответе.

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

Сценарий пересылки

В следующем примере входящий запрос перенаправляется на серверную часть.

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

Сценарий пересылки и преобразования

Следующий пример пересылает входящий запрос и преобразует ответ, возвращаемый серверной частью.

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

Поддерживаемые пространства имен

Не все пространства имен C# поддерживаются. В настоящее время вы можете использовать функции только из следующих пространств имен.

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

Примеры в DocuSign коннекторе см. в разделе Power Platform Коннекторы на GitHub.

Вопросы и ответы по пользовательскому коду

Чтобы узнать больше о пользовательском коде, перейдите к Шагу 4: (Необязательно) Используйте поддержку пользовательского кода.

В: Можно ли использовать несколько скриптов для одного пользовательского коннектора?
A: Нет, поддерживается только один файл скрипта для каждого пользовательского коннектора.

В: При обновлении моего пользовательского коннектора возникает внутренняя ошибка сервера. В чем может быть проблема?
A: Скорее всего, это проблема компиляции вашего кода. В будущем мы отобразим полный список ошибок компиляции, чтобы улучшить этот опыт. На данный момент в качестве обходного пути мы рекомендуем использовать вспомогательные классы для локального тестирования ошибок компиляции.

В: Могу ли я добавить ведение журнала в свой код и получить трассировку для отладки?
A: В настоящее время нет, но поддержка этого будет добавлена в будущем.

В: Как я могу в это время протестировать свой код?
A: Протестируйте локально и убедитесь, что вы можете скомпилировать код, используя только пространства имен, указанные в поддерживаемых пространствах имен. Информацию о локальном тестировании см. в разделе Написание кода в пользовательском коннекторе.

В: Существуют ли какие-либо ограничения?
Ответ. Да. Ваш скрипт должен быть выполнен в течение 2 минут, а размер файла скрипта не может превышать 1 МБ. Этот новый двухминутный тайм-аут применяется ко всем вновь созданным пользовательским коннекторам. Для существующих пользовательских коннекторов клиентам необходимо обновить коннектор, чтобы применить новое время ожидания.

В: Могу ли я создать свой собственный http-клиент в коде скрипта?
A: В настоящее время да, но в будущем мы это заблокируем. Рекомендуемый способ — использовать метод this.Context.SendAsync .

В: Могу ли я использовать пользовательский код с локальным шлюзом данных?
A: В настоящее время нет.

Поддержка виртуальной сети

При использовании соединителя в Power Platform среде, связанной с виртуальной сетью, применяются следующие ограничения:

Context.SendAsync использует общедоступную конечную точку, поэтому он не может получить доступ к данным из частных конечных точек, представленных в виртуальной сети.

Общие известные проблемы и ограничения

В некоторых регионах заголовок OperationId может возвращаться в кодировке Base64. Если значение OperationId требуется для какой-либо реализации, его необходимо декодировать из Base64, чтобы использовать следующим образом.

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
}

Следующий шаг

Создайте собственный коннектор с нуля

Предоставление отзыва

Мы очень ценим отзывы о проблемах с нашей платформой соединителей и новые идеи о функциях. Чтобы оставить отзыв, перейдите на страницу Сообщить о проблемах или получить помощь с соединителями и выберите тип отзыва.

Поделиться через