Erläuterung der Anrufmodi

API-Trigger-Aufrufmodi wurden speziell für das Erstellen und Folgen von Auftragsausführungen im Orchestrator entwickelt.

Die grundlegende Herausforderung bei der HTTP-basierten Kommunikation besteht darin, dass sie von vornherein synchron ist: Normalerweise sendet der Client eine Anforderung und wartet auf die Antwort vom Server. Im Zusammenhang mit Roboteraufträgen ist es im Orchestrator jedoch nicht möglich, die Verbindung offen zu halten, bis der Auftrag abgeschlossen ist.

Um dies zu umgehen, haben wir das HTTP-Protokoll verwendet, um mehrere Aufrufmodi zu modellieren. Diese Modi verwenden Standard-HTTP-Methoden, Statuscodes und Header, um Aufträge innerhalb des Systems zu erstellen, zu überwachen und das Ergebnis abzurufen, ohne die Verbindung unnötig offen zu halten. Jeder der vorgeschlagenen Aufrufmodi hat Vor- und Nachteile, sodass Sie denjenigen auswählen können, der für Ihre Integrationsanforderungen am besten geeignet ist. Denken Sie daran, dass zur Sicherstellung der sicheren Kommunikation jeder Aufruf eine ordnungsgemäße Authentifizierung durch Bearer-Token erfordert.

Wichtig:

Bekanntes Problem

Bei Anforderungen kann manchmal der Cloudflare-Fehler 502 Bad Gateway zurückgegeben werden, der dadurch verursacht wird, dass eine große Anzahl von Verbindungen über längere Zeiträume aufrecht erhalten wird. Der zugrundeliegende Auftrag einer solchen Anforderung wurde eventuell trotz des Fehlers ausgeführt, sodass Sie seinen Status im Orchestrator überprüfen können.

Dieses Problem tritt nur zeitweise auf und alle nachfolgenden Anforderungen funktionieren wie erwartet.

Asynchrones Polling

Dieser Aufrufmodus beinhaltet einen Aufruf mit dem vorkonfigurierten HTTP-Verb, um einen neuen Auftrag auszulösen und einen Status-URI zu erhalten. Der Status-URI muss dann manuell abgefragt werden, bis der Auftrag abgeschlossen ist. An diesem Punkt wird der Aufruf an einen anderen Endpunkt umgeleitet, der zum Abrufen des Auftragsergebnisses (Ausgabe oder Fehler) verwendet wird.

Asynchroner Abfrage-Workflow, bei dem die Fertigstellung des Auftrags von zwischenzeitlichen manuellen Aufrufen der Antwortstelle abhängt.

Der erste Aufruf erfolgt mit dem konfigurierten HTTP-Verb (GET, POST, PUT, DELETE), das den zugehörigen Auftrag im Orchestrator erstellt. Bei der erfolgreichen Auftragserstellung antwortet das System mit einem HTTP-Statuscode 202 (Akzeptiert) und einem Status-URI im Speicherort-Header.

Sobald der Auftrag erstellt wurde, wird erwartet, dass Sie den Status regelmäßig abfragen. Während dieser Abfrage wird bei jeder GET-Anfrage an die Status-URI ein HTTP-Statuscode 200 (OK) zurückgegeben, solange der Auftrag läuft. Wenn der Auftrag abgeschlossen ist, gibt die nächste GET-Anforderung den HTTP-Statuscode 303 (Siehe Sonstige) an den Status-URI zurück und leitet Sie zum Ausgabe-URI (über den Speicherort-Header) um. Es wird erwartet, dass Sie dem Ausgabe-URI folgen, um das Auftragsergebnis (Ausgabe oder Fehler) abzurufen.

Stellen Sie immer sicher, dass Sie ein gültiges Bearer-Token in den Header jedes Aufrufs aufnehmen, um eine erfolgreiche Authentifizierung zu ermöglichen.

JavaScript-Beispiel

Dieses Beispiel veranschaulicht, wie ein Auftrag über einen API-Trigger in einem Browser im asynchronen Abrufmodus gestartet wird.

const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));

const url = 'https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>';
const token = '<PERSONAL_ACCESS_TOKEN>'; // could also be an access token retrieved via OAuth

const body = {
  'argument1': 123,
  'argument2': 'my string',
  '$callMode': 'AsyncRequestReply' // optional argument to force call mode to AsyncRequestReply
}

// if invocation is done by GET, place the parameters in query string and remove the 'Content-Type' header
const invokeRequestOptions = {
  method: 'POST',
  headers: new Headers({ 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }),
  body: JSON.stringify(body),
};

const redirectRequestOptions = {
  method: "GET",
  credentials: 'same-origin',
  headers: new Headers({ Authorization: `Bearer ${token}` }),
  redirect: "follow", // this option must be set to follow, otherwise an 'opaqueredirect' response is returned
};

const response = await fetch(url, invokeRequestOptions);
let newLocation = response.headers.get("Location");

// first response should be 202 and have a location header
console.log(`Got ${response.status}, with location: ${newLocation}`);

for (let i = 0; i < 20; i++) {
  await sleep(SLEEP_DURATION);

  // follow the location header to the new endpoint
  const statusResponse = await fetch(newLocation, redirectRequestOptions);

  // if the response was redirected (and automatically followed), then the output endpoint has been reached
  // the output of the job can be found in the body of the response in JSON format
  if (statusResponse.status != 200 || statusResponse.redirected)
  {
    // read the job output
    const output = await statusResponse.json();
    console.log(`Got ${statusResponse.status}, with body: ${JSON.stringify(output)}`);

    break;
}

C#-Beispiel

Dieses Beispiel veranschaulicht, wie ein Auftrag über einen API-Trigger aus einer C#-basierten Anwendung gestartet wird, wobei der asynchrone Abrufmodus verwendet wird.

public async Task<string> AsyncPollingExample()
{
    const string url = "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>";
    const string token = "<PERSONAL_ACCESS_TOKEN>"; // could also be an access token retrieved via OAuth

    // create an http client that does not follow redirects and adds a bearer token on each call
    var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var arguments = new Dictionary<string, object>
    {
        { "argument1", 123 },
        { "argument2", "my string" },
        { "$callMode", "AsyncRequestReply" }, // optional argument to force call mode to AsyncRequestReply
    };

    var httpResponseStart = await httpClient.PostAsJsonAsync(url, arguments);
    var redirectUri = httpResponseStart.Headers.Location;

    if (httpResponseStart.StatusCode != HttpStatusCode.Accepted)
        throw new Exception("Could not invoke workflow");

    while (true)
    {
        var httpPollingResponse = await httpClient.GetAsync(redirectUri);

        if (httpPollingResponse.StatusCode == HttpStatusCode.Redirect)
        {
            var outputLocation = httpPollingResponse.Headers.Location;
            var outputResponse = await httpClient.GetAsync(outputLocation);
            var jobOutput = await outputResponse.Content.ReadAsStringAsync();

            return jobOutput;
        }

        await Task.Delay(1000);
    }
}

Asynchrones Fire-and-Forget

Der Fire-and-Forget-Aufrufmodus gibt bei erfolgreicher Auftragserstellung den Status „200 OK“ ohne weitere Informationen über den Auftrag zurück.

Asynchroner Fire-and-Forget-Workflow, bei dem der Auftrag ohne Zwischenaufrufe abgeschlossen wird.

JavaScript-Beispiel

Dieses Beispiel veranschaulicht, wie ein Auftrag über einen API-Trigger in einem Browser gestartet wird, indem der asynchrone Fire-and-Forget-Aufrufmodus verwendet wird.

const url = 'https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>';
const token = '<PERSONAL_ACCESS_TOKEN>'; // could also be an access token retrieved via OAuth
  
const body = {
  'argument1': 123,
  'argument2': 'my string',
  '$callMode': 'FireAndForget' // optional argument to force call mode to FireAndForget
}

const options = {
  method: 'POST',
  headers: new Headers({ 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }),
  body: JSON.stringify(body),
};

let response = await fetch(url, options);

console.log(`Got ${response.status}`);

C#-Beispiel

Dieses Beispiel veranschaulicht, wie ein Auftrag über einen API-Trigger aus einer C#-basierten Anwendung unter Verwendung des asynchronen Fire-and-Forget-Aufrufmodus gestartet wird.

public async Task FireAndForgetExample()
{
    const string url = "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>";
    const string token = "<PERSONAL_ACCESS_TOKEN>"; // could also be an access token retrieved via OAuth

    // create an http client that does not follow redirects and adds Bearer <token> on each call
    // if the follow redirects option is enabled, C# will not add a bearer token by default after the redirect
    var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var arguments = new Dictionary<string, object>
    {
        { "argument1", 123 },
        { "argument2", "my string" },
        { "$callMode", "FireAndForget" }, // optional argument to force call mode to LongPolling
    };

    var response = await httpClient.PostAsJsonAsync(url, arguments);

    Console.WriteLine(response.StatusCode);
}

Synchronisierung (Long Polling)

Dieser Aufrufmodus beinhaltet einen ersten Aufruf, der blockiert und eine Weile wartet, bis der Auftrag abgeschlossen ist, gefolgt von mehreren möglichen blockierenden Aufrufen und Umleitungen. Schließlich wird nach Abschluss des Auftrags das Auftragsergebnis (Ausgabe oder Fehler) abgerufen.

Je nach Mandanteneinstellungen kann die Authentifizierung für alle Aufrufe oder nur für den ersten Aufruf erforderlich sein.

Synchronisierter Workflow (Long Polling), bei dem das Ergebnis, ob erfolgreich oder nicht, mit dem ersten Aufruf zurückgegeben wird.

Synchronisierter Workflow (mit langen Abrufen), bei dem mehrere Aufrufe automatisch für den Auftragsabschluss durchgeführt werden.

Der erste Aufruf erfolgt mit dem konfigurierten HTTP-Verb (GET, POST, PUT, DELETE), das den zugehörigen Auftrag im Orchestrator erstellt. Bei erfolgreicher Auftragserstellung blockiert das System den aktuellen Aufruf, während es auf den Abschluss des Auftrags wartet. Wenn der Auftrag abgeschlossen ist, wird der blockierte Aufruf freigegeben und eine Antwort mit den Auftragsausgabeargumenten wird zurückgesendet.

Wenn der Auftrag nach einer Zeitüberschreitung noch nicht abgeschlossen ist, antwortet das System mit einem HTTP-Statuscode 303 (siehe „Sonstige“) und leitet zur Status-URI weiter (über den Header „Speicherort“). Es wird erwartet, dass Sie dem Status-URI folgen, der bis zum Abschluss des Auftrags gesperrt ist. Wenn der Auftrag nach einer Zeitüberschreitung nicht abgeschlossen ist, werden Sie erneut zur Status-URI umgeleitet, wodurch eine Umleitungsschleife entsteht. Nach erfolgreichem Abschluss des Auftrags wird das Auftragsergebnis (Ausgabe oder Fehler) als Teil der HTTP-Antwort abgerufen.

Standardmäßig müssen alle Aufrufe ein gültiges Bearer-Token zur Autorisierung enthalten. Wenn jedoch die Option Authentifizierungs-Header für Umleitungen von synchronen API-Triggern erforderlich in den Mandanteneinstellungen nicht ausgewählt ist, erfordert nur der erste Aufruf des Triggers den Authentifizierungs-Header. Nachfolgende Aufrufe des Statusendpunkts können ohne Autorisierungsheader erfolgen.

Die maximale Auftragsdauer für diesen Anrufmodus beträgt 15 Minuten.

JavaScript-Beispiel

Dieses Beispiel veranschaulicht, wie ein Auftrag über einen API-Trigger in einem Browser gestartet wird, wobei der Synchronisierungsaufrufmodus (Long Polling) verwendet wird.

const url = 'https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>';
const token = '<PERSONAL_ACCESS_TOKEN>'; // could also be an access token retrieved via OAuth

const body = {
  'argument1': 123,
  'argument2': 'my string',
  '$callMode': 'LongPolling' // optional argument to force call mode to LongPolling
}

const options = {
  method: 'POST',
  headers: new Headers({ 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }),
  body: JSON.stringify(body),
  redirect: "follow", // follow redirects automatically
};

let response = await fetch(url, options);
const output = await response.json();

console.log(`Got ${response.status} with body ${JSON.stringify(output)}`);

C#-Beispiel

Dieses Beispiel veranschaulicht, wie ein Auftrag über einen API-Trigger aus einer C#-basierten Anwendung gestartet wird, wobei der Synchronisierungsaufrufmodus (Long Polling) verwendet wird.

public async Task SyncExample()
{
    const string url = "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/t/<INVOKE_URL>";
    const string token = "<PERSONAL_ACCESS_TOKEN>"; // could also be an access token retrieved via OAuth

    // create an http client that does not follow redirects and adds Bearer <token> on each call
    // if the follow redirects option is enabled, C# will not add a bearer token by default after the redirect
    var httpClient = new HttpClient(new HttpClientHandler { AllowAutoRedirect = false });
    httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var arguments = new Dictionary<string, object>
    {
        { "argument1", 123 },
        { "argument2", "my string" },
        { "$callMode", "LongPolling" }, // optional argument to force call mode to LongPolling
    };

    var response = await httpClient.PostAsJsonAsync(url, arguments);

    while(response.StatusCode == HttpStatusCode.Redirect)
    {
        // in case of redirection, keep following the latest location in the header
        var location = response.Headers.Location;
        response = await httpClient.GetAsync(location);
    }

    // read the job output/error from the last request
    var jobOutput = response.Content.ReadAsStringAsync();

    Console.WriteLine(jobOutput);
}