UiPath Documentation
integration-service
latest
false
Integration Service-Benutzerhandbuch
Wichtig :
Dieser Inhalt wurde maschinell übersetzt. Die Connector-Pakete, die in Integration Service verfügbar sind, werden maschinell übersetzt. Es kann 1–2 Wochen dauern, bis die Lokalisierung neu veröffentlichter Inhalte verfügbar ist.

Skript

Configure Connector Builder scripts that run JavaScript before or after API requests, for every request in a connector or for a single resource, and the order in which they run.

Connector Builder lets you write JavaScript that runs before or after the API requests made by your connector. Use pre-request scripts to modify outgoing requests and post-request scripts to process incoming responses. Scripts on the Global Scripts tab run for every request the connector makes, and scripts on a resource's Scripts tab run only for that resource.

When to use scripts​

Scripts are useful when you need to customize how your connector calls the provider, such as:

  • Einfügen oder Überschreiben von Anforderungsheadern, Parametern oder Text vor dem Senden
  • Dynamisches Erstellen der Anbieter-URL basierend auf Konfigurationswerten
  • Transformieren eines Anbieterantworttexts, bevor er an den Workflow zurückgegeben wird
  • Stoppen einer Anforderung basierend auf benutzerdefinierten Bedingungen, ohne die Anbieter-API aufzurufen

Skripte für eine einzelne Ressource​

Jede Ressource hat auch eine eigene Registerkarte „Skripte“ neben Parametern, Anforderungsfeldern, Antwortfeldern und Aktivitätsdesigner. Sie bietet die gleichen Vorab-Anforderungsskript- und Nach-Anforderungsskript- Editoren, die gleichen Snippets und die gleichen Variablen und den done() Vertrag wie die Registerkarte Globale Skripte auf Connector-Ebene.

Der Unterschied besteht im Scope:

  • Für jede Anforderung, die der Connector stellt, wird ein Skript auf der Registerkarte Globale Skripte ausgeführt.
  • Ein Skript auf der Registerkarte Skripte einer Ressource wird nur für diese Ressource ausgeführt.

Verwenden Sie ein Ressourcenskript, wenn die Logik für einen Endpunkt gilt, und ein globales Skript, wenn sie für den gesamten Connector gilt.

Schreiben von Skripten​

So öffnen Sie die Registerkarte Globale Skripte:

  1. Öffnen Sie im Integration Service den Connector-Generator und wählen Sie Ihren benutzerdefinierten Connector aus.
  2. Wählen Sie in der oberen Navigation Globale Skripte aus.
  3. Erweitern Sie Voranforderungsskript oder Nachanforderungsskript und geben Sie Ihr JavaScript ein.

Skripte werden in einer Sandbox-JavaScript-Umgebung ausgeführt, ohne Netzwerkzugriff und ohne Möglichkeit, Pakete zu importieren.

Standardmäßig integrierte JavaScript-Instanzen sind verfügbar: JSON, Date, Array, Object, URL, encodeURIComponent, URLSearchParams, TextEncoder, TextDecoder, btoa, atob, crypto, Blob, FormData, Headers, Intl und BigInt.

Wichtig:

Buffer ist nicht verfügbar. Verwenden Sie stattdessen btoa und atob für die Base64-Codierung.

Folgendes ist in der Sandbox nicht verfügbar:

KategorieNicht verfügbar
Auswertung und Importeeval, ein beliebiger require() -Aufruf, eine import - oder export -Anweisung auf oberster Ebene, ein dynamischer import(...) -Ausdruck
Netzwerkfetch, XMLHttpRequest, WebSocket
Timer und WorkersetTimeout, setInterval, setImmediate, Worker, importScripts, postMessage
Runtime und globale LaufzeitenDeno, process, globalThis, self, window, WebAssembly, Buffer

Die done() -Funktion​

Jedes Skript muss done() aufrufen, um die Fertigstellung zu signalisieren. done() beendet die Ausführung sofort – Code, der nach done() geschrieben wurde, ist nicht erreichbar.

// Pass through unchanged
done();

// Override one or more output values
done({
  request_vendor_headers: updatedHeaders
});

// Return multiple overrides
done({
  request_vendor_body: newBody,
  request_vendor_headers: newHeaders
});

// Stop the request — do not call the vendor API
done({ continue: false });

// Stop the request and return an error
done({
  continue: false,
  response_status_code: 400,
  response_error_message: "Invalid action"
});
// Pass through unchanged
done();

// Override one or more output values
done({
  request_vendor_headers: updatedHeaders
});

// Return multiple overrides
done({
  request_vendor_body: newBody,
  request_vendor_headers: newHeaders
});

// Stop the request — do not call the vendor API
done({ continue: false });

// Stop the request and return an error
done({
  continue: false,
  response_status_code: 400,
  response_error_message: "Invalid action"
});

Verwenden von Snippets​

Wählen Sie Snippets im Skriptbereich aus, um Codevorlagen in den aktiven Skript-Editor einzufügen.

Der Bereich Voranforderungsskript bietet die folgenden Vorlagen, die unter Voranforderungsskripts gruppiert sind:

  • Anbieter-URL aktualisieren – Legt request_vendor_path auf eine vollständige URL fest und ersetzt die Anbieter-URL für diese Anforderung.
  • Verwenden einer Konfiguration – Liest einen Wert von configuration (die Basis-URL des Connectors im Beispiel) und sendet ihn als Anforderungsheader an den Anbieter.
  • Eine Anbieteranforderung überspringen – Legt continue auf false fest, sodass die Anforderung nie an den Anbieter gesendet wird.

Der Bereich Skript nach der Anforderung bietet die folgenden Vorlagen, die unter Skripte nach der Anforderung gruppiert sind:

  • Antworttext aktualisieren – Kopiert response_body in eine lokale Variable, fügt ein Feld hinzu und gibt den geänderten Text zurück.
  • Generierung von SR-Metadaten aus Anbietermetadaten – Erstellt Standardressourcenfeldmetadaten aus einer Anbietermetadatenantwort und leitet den Typ, das Format, den Anzeigenamen, die Beschreibung, die unterstützten Methoden und die Aufzählungswerte jedes benutzerdefinierten Felds ab.

Voranforderungsskripts​

Ein Voranforderungsskript wird ausgeführt, bevor jeder API-Aufruf an den Anbieter gesendet wird. Variablen mit Schreib- oder Lese- und Schreibzugriff können über done() festgelegt werden.

VariableZugriffBeschreibung
request_methodLesenHTTP-Methode des API-Aufrufs (GET, POST usw.).
request_vendor_methodLesen und SchreibenHTTP-Methode, die an den Anbieter übergeben wird.
request_headersLesenAnforderungsheader, die als Teil des API-Aufrufs übergeben wurden.
request_vendor_headersLesen und SchreibenHeader, die an den Anbieter gesendet werden.
request_pathLesenAnforderungspfad des API-Aufrufs.
request_vendor_pathLesen und SchreibenAnforderungspfad, der an den Anbieter gesendet wird. Wenn der Pfad mit http beginnt, wird er als vollständige Anforderungs-URL verwendet.
request_path_variablesLesenAus der URL-Vorlage extrahierte Pfadvariablen.
request_parametersLesenAbfrageparameter, die als Teil des API-Aufrufs übergeben werden.
request_vendor_parametersLesen und SchreibenAbfrageparameter, die an den Anbieter gesendet werden.
request_bodyLesenAnforderungstext, der als Teil des API-Aufrufs als Zeichenfolge übergeben wurde.
request_body_rawLesenDer Anforderungstext wurde als Teil des API-Aufrufs als unverarbeitete Zeichenfolge übergeben.
request_vendor_bodyLesen und SchreibenAnforderungstext, der an den Anbieter gesendet wird. Akzeptiert Zeichenfolge, Liste oder Zuordnung beim Schreiben.
request_body_mapLesenAnforderungstext, der als Teil des API-Aufrufs als Zuordnung übergeben wurde.
request_vendor_body_mapLesenAnforderungstext, der als Zuordnung an den Anbieter gesendet wird.
request_vendor_urlLesenVollständige Endpunkt-URL, die für den Anbieteraufruf verwendet wird.
request_expressionLesenCEQL-Parameter where in eine Liste von {attribute, value, operator} -Zuordnungen konvertiert.
request_previous_responseLesenAntworttext der vorherigen verketteten Ressource. null wenn es nicht Teil einer Kette ist.
request_previous_response_headersLesenAntwortheader von der vorherigen verketteten Ressource. null wenn es nicht Teil einer Kette ist.
request_root_keyLesen und Schreibendot-notation-Pfad zum Erstellen eines Unterobjekts in der JSON-Nutzlast der Anforderung (z. B data.record).
object_nameLesenkanonischer Objektname für die Anforderung.
vendor_object_nameLesenName des Anbieterobjekts. Entspricht object_name , es sei denn, er wird auf der Ressource überschrieben.
configurationLesenEigenschaften der Connector-Konfiguration.
response_status_codeSchreibenHTTP-Statuscode, der zurückgegeben werden soll, wenn continue false ist.
response_error_messageSchreibenFehlermeldung, die zurückgegeben werden soll, bevor die Anforderung an den Anbieter gesendet wird.
response_bodySchreibenAntworttext, der zurückgegeben werden soll, wenn continue false ist.
response_body_rawSchreibenAntworttext als Zeichenfolge, die zurückgegeben werden soll, wenn continue false ist.
response_root_keyLesen und Schreiben.Pfad zur Beschränkung der Antwort auf ein Unterobjekt (z. B data.records).
multipart_hook_context_itemsLesen und SchreibenMehrteilige Formularelemente für Dateiuploadanforderungen.
continueSchreibenAuf false festlegen, um den Anbieteraufruf zu überspringen. Die Standardeinstellung ist true.

Beispiel: Fügen Sie einen dynamischen Header aus der Konfiguration ein​

var headers = request_vendor_headers || {};
var config = configuration || {};

headers['Authorization'] = 'Bearer ' + config['oauth_token'];

done({ request_vendor_headers: headers });
var headers = request_vendor_headers || {};
var config = configuration || {};

headers['Authorization'] = 'Bearer ' + config['oauth_token'];

done({ request_vendor_headers: headers });

Beispiel: Überschreiben Sie den URL-Pfad des Anbieters​

var baseUrl = configuration['base_url'];
if (!baseUrl) {
  done({ continue: false, response_error_message: "Missing configuration: 'base_url'" });
  return;
}

var apiVersion = configuration['api_version'] || 'v1';
var modelId = request_path_variables.modelId;
var vendorUrl = baseUrl.startsWith('http') ? baseUrl : 'https://' + baseUrl;

done({
  request_vendor_path: vendorUrl + '/' + apiVersion + '/models/' + modelId + '/completions'
});
var baseUrl = configuration['base_url'];
if (!baseUrl) {
  done({ continue: false, response_error_message: "Missing configuration: 'base_url'" });
  return;
}

var apiVersion = configuration['api_version'] || 'v1';
var modelId = request_path_variables.modelId;
var vendorUrl = baseUrl.startsWith('http') ? baseUrl : 'https://' + baseUrl;

done({
  request_vendor_path: vendorUrl + '/' + apiVersion + '/models/' + modelId + '/completions'
});

Beispiel: Ändern Sie den Anforderungstext​

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});
var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

Skripte nach der Anforderung​

Ein Post-Anforderungsskript wird ausgeführt, nachdem eine Antwort vom Anbieter empfangen wurde. Alle Voranforderungsvariablen bleiben als Lesen verfügbar. Die antwortspezifischen Variablen unten werden hinzugefügt, und configuration wird zu Lesen und Schreiben. Variablen mit Schreib- oder Lese- und Schreibzugriff können über done() festgelegt werden.

VariableZugriffBeschreibung
response_iserrorLesentrue wenn die Anbieterantwort einen Fehler anzeigt (Statuscodes außerhalb von 200–207).
response_status_codeLesen und SchreibenHTTP-Statuscode des Anbieters.
response_bodyLesen und SchreibenAntworttext des Anbieters.
response_body_rawLesen und SchreibenUnformatierter Antworttext des Anbieters als Zeichenfolge.
response_body_raw_mapLesenUnformatierter Antworttext des Anbieters als Zuordnung.
response_body_mapLesenAntworttext des Anbieters als Zuordnung.
response_headersLesen und SchreibenAntwortheader des Anbieters.
response_error_messageSchreibenFehlermeldung, die zurückgegeben werden soll. Konvertiert die Antwort in einen Fehler.
response_root_keyLesen und Schreiben.Pfad zur Beschränkung der Antwort auf ein Unterobjekt (z. B data.records).
configurationLesen und SchreibenEigenschaften der Connector-Konfiguration. Änderungen bleiben auf der Connector-Instanz bestehen.
multipart_hook_context_itemsLesen und SchreibenMehrteilige Formularelemente für Dateiuploadanforderungen.
metadata_mergeSchreibenAuf true festlegen, um Anbietermetadaten mit Modellmetadaten zu kombinieren.
Tipp:

Beginnen Sie jedes Nach-Anforderungs-Skript mit einem Fehlerschutz. Wenn die Antwort ein Fehler ist, rufen Sie done() ohne Argumente auf, um sie unverändert zu übergeben.

Beispiel: Transformieren Sie den Antworttext​

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

body.processed = true;
body.timestamp = new Date().toISOString();

done({ response_body: body });
if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

body.processed = true;
body.timestamp = new Date().toISOString();

done({ response_body: body });

Utility-Funktionen​

Die folgenden Dienstprogrammfunktionen sind in beiden Skripttypen verfügbar:

FunctionBeschreibung
console.log()Gibt eine Debugging-Meldung aus.

Bringen Sie Ihren eigenen LLM-Connector-Anwendungsfall ein​

Wenn Sie einen Connector für einen LLM-Anbieter erstellen – z. B. ein selbst gehostetes Modell oder einen Inferenzendpunkt eines Drittanbieters – können Sie mit Global Scripts Anforderungen und Antworten so anpassen, dass sie dem erwarteten Vertrag entsprechen, ohne jede Ressource einzeln zu ändern.

Tipp:

Bei gängigen LLM-Anbietern (AWS Bedrock, Azure OpenAI, Google Vertex AI, OpenAI V1 kompatibel) können Sie mit einer Connector-Vorlage beginnen, die das Authentifizierungssetup und die Skripte für Sie vorab ausfüllt. Weitere Informationen finden Sie unter Verwenden von Connector-Vorlagen.

Die folgenden Skripte zeigen eine vollständige Einrichtung vor und nach der Anforderung für dieses Szenario.

Voranforderung: Legen Sie Authentifizierungsheader fest​

Fügen Sie den API-Schlüssel des Anbieters aus der Connector-Konfiguration ein und erzwingen Sie die erwartete Content-Type:

var headers = {
  'Content-Type': 'application/json',
  'x-api-key': configuration['api_key']
};

done({
  request_vendor_headers: headers,
  request_vendor_body: request_body_map
});
var headers = {
  'Content-Type': 'application/json',
  'x-api-key': configuration['api_key']
};

done({
  request_vendor_headers: headers,
  request_vendor_body: request_body_map
});

Voranforderung: Fügen Sie eine Systemnachricht ein​

Legen Sie die Standard-Modellparameter fest und stellen Sie sicher, dass in jeder Konversation, die an das Modell gesendet wird, eine Systemmeldung vorhanden ist:

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

var hasSystemMessage = body.messages.some(function(msg) {
  return msg.role === 'system';
});

if (!hasSystemMessage) {
  body.messages.unshift({
    role: 'system',
    content: 'You are a helpful assistant.'
  });
}

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});
var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

var hasSystemMessage = body.messages.some(function(msg) {
  return msg.role === 'system';
});

if (!hasSystemMessage) {
  body.messages.unshift({
    role: 'system',
    content: 'You are a helpful assistant.'
  });
}

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

Nachanforderung: Verarbeiten Sie das Auswahl-Array​

Iterieren Sie das choices -Array in der Anbieterantwort und fügen Sie benutzerdefinierte Metadaten hinzu, bevor Sie zum Workflow zurückkehren:

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

if (body.choices && body.choices.length > 0) {
  body.choices.forEach(function(choice) {
    choice.processed_by = 'connector-post-script';
  });
}

body.custom_metadata = {
  processed: true,
  timestamp: new Date().toISOString()
};

done({ response_body: body });
if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

if (body.choices && body.choices.length > 0) {
  body.choices.forEach(function(choice) {
    choice.processed_by = 'connector-post-script';
  });
}

body.custom_metadata = {
  processed: true,
  timestamp: new Date().toISOString()
};

done({ response_body: body });

Best Practices​

  • Immer done()aufrufen – ein Skript, das done() nicht aufruft, hängt die Anforderung auf.
  • Kopieren Sie Variablen vor dem Mutieren – die Laufzeit verwendet den strikten Modus. Zuerst eine lokale Variable zuweisen: var headers = request_vendor_headers;, dann ändern Sie headers.
  • Schreiben Sie keinen Code nach done() – er ist nicht erreichbar.
  • Prüfen Sie auf null oder undefined – request_body und request_vendor_body sind undefined für GET- und DELETE-Anforderungen.
  • Use continue: false to short-circuit — skip the vendor call and return your own response. Post-request scripts still run on that response.

Execution order​

When a connector has both a global script and a resource script for the same phase, both scripts run, in this order:

  1. Global pre-request script
  2. Resource pre-request script
  3. The request is sent to the provider
  4. Global post-request script
  5. Resource post-request script
Wichtig:

The post-request chain does not run in reverse. The global post-request script receives the raw provider response first, and can change or reject it before the resource post-request script runs.

Example: a global script and a resource script on one activity​

Consider a connector with the following scripts:

  • Global pre-request: adds an X-Acme-Tenant header from configuration.
  • Global post-request: maps the provider's error envelope onto the matching HTTP status code.
  • GET /contacts resource: a pre-request script that maps paging parameters, and a post-request script that reshapes the payload.
ReihenfolgeSkriptWas angezeigt wird
1Global pre-requestThe request as built from the activity input.
2Resource pre-requestThe request, including the tenant header added in step 1.
–Provider call–
3Global post-requestThe raw provider response.
4Resource post-requestThe response as left by step 3.

If both pre-request scripts set Authorization, the provider receives the value from the resource script, because it runs last. If the global post-request script sets response_error_message, the request ends with that error and step 4 does not run. Setting only an error response_status_code does not stop the chain.

When a pre-request script stops the request​

If a global or resource pre-request script calls done() with continue: false, the request is not sent to the provider:

  • Pre-request scripts that haven't run yet are skipped. For example, if the global pre-request script stops the request, the resource pre-request script does not run.
  • Both post-request scripts still run, in the usual order, on the response returned by the script that stopped the request.
  • If that script returned no response body, the post-request scripts receive an empty body: an empty array for a paginated resource, and an empty response otherwise.

To end the request with an error instead, set response_error_message. In a pre-request or post-request script, it ends the request immediately with that error, and no later script runs, including post-request scripts. The status code is the value of response_status_code, or 400 if it isn't set.

War diese Seite hilfreich?

Verbinden

Benötigen Sie Hilfe? Support

Möchten Sie lernen? UiPath Academy

Haben Sie Fragen? UiPath-Forum

Auf dem neuesten Stand bleiben