呼び出しモードの説明

API トリガー呼び出しモードが、HTTP ベースの通信を介したジョブの実行を作成および追跡する方法。

API トリガーの呼び出しモードは、Orchestrator でジョブの実行を作成および追跡するために特別に設計されています。

HTTP ベースの通信の根本的な課題として、本質的に同期的である、ということがあります。通常、クライアントは要求を送信し、サーバーからの応答を待ちます。しかしロボットのジョブのコンテキストにおいては、ジョブが完了するまで接続を開いたままにすることが Orchestrator でサポートされていません。

To work around this, we’ve used the HTTP protocol to model multiple call modes. These modes rely on standard HTTP methods, status codes, and headers to create, monitor and get the result of jobs within the system, without unnecessarily keeping the connection open.

Each of the proposed call modes has advantages and disadvantages, so you can choose the one that is best suited for your integration needs. Bear in mind that, to ensure secure communication, each call requires proper authentication through bearer tokens.

重要:

既知の問題: 多数の接続が長時間にわたって維持されていることが原因で、要求が 502 Bad Gateway Cloudflare エラーを返すことがあります。このような要求の基になるジョブはエラーにもかかわらず実行された可能性があるため、Orchestrator でそのステートを確認できます。

この問題は断続的に発生し、後続の要求は想定どおりに動作します。

非同期ポーリング

この呼び出しモードでは、設定済みの HTTP 動詞で呼び出しを行って新しいジョブをトリガーし、ステータスの URI を受け取ります。その後のステータス URI は、ジョブが完了するまで手動でポーリングする必要があります。この時点で呼び出しが別のエンドポイントにリダイレクトされます。このエンドポイントを使用して、ジョブの結果 (出力またはエラー) が取得されます。

図 1. 非同期ポーリングのワークフロー

最初の呼び出しは、設定済みの HTTP 動詞 (GET、POST、PUT、DELETE) を使用して行われ、関連するジョブが Orchestrator 内に作成されます。ジョブが正常に作成されると、システムは HTTP ステータス コード 202 (Accepted) と Location ヘッダー内のステータス URI で応答します。

Once the job is created, you are expected to periodically poll its status. During this polling process, as long as the job is running, each GET request to the status URI returns an HTTP status code 200 (OK). When the job is completed, the next GET request to the status URI returns an HTTP status code 303 (See Other), redirecting to the output URI (via the Location header).

You are expected to follow the output URI to retrieve the job result (output or error).

認証を成功させるために、すべての呼び出しのヘッダーに有効なベアラー トークンを含めるようにしてください。

JavaScript の例

この例では、非同期ポーリング呼び出しモードを使用して、ブラウザーから API トリガーを介してジョブを開始する方法を示します。

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

const url = 'https://{yourDomain}/{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# の例

この例では、非同期ポーリング呼び出しモードを使用して、C# ベースのアプリケーションから API トリガーを介してジョブを開始する方法を示します。

public async Task<string> AsyncPollingExample()
{
    const string url = "https://{yourDomain}/{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);
    }
}

非同期で完了を待たずに実行 (fire & forget)

fire & forget の呼び出しモードは、ジョブが正常に作成されると 200 OK ステータスを返します。ジョブに関するその他の情報は取得されません。

図 2. 非同期で完了を待たずに実行 (fire & forget) のワークフロー

JavaScript の例

この例では、非同期で完了を待たずに実行 (fire & forget) のモードを使用して、ブラウザーから API トリガーを介してジョブを開始する方法を示します。

const url = 'https://{yourDomain}/{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# の例

この例では、非同期で完了を待たずに実行 (fire & forget) のモードを使用して、C# ベースのアプリケーションから API トリガーを介してジョブを開始する方法を示します。

public async Task FireAndForgetExample()
{
    const string url = "https://{yourDomain}/{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);
}

同期 (ロングポーリング)

この呼び出しモードでは、最初の呼び出しでブロックが行われ、ジョブが完了するまでしばらく待機し、その後にブロック呼び出しとリダイレクトが数回行われる可能性があります。最終的には、ジョブが完了すると、ジョブの結果 (出力またはエラー) が取得されます。

テナントの設定によっては、すべての呼び出しに認証が必要になる場合もあれば、最初の呼び出しのみに認証が必要な場合もあります。

図 3. 同期 (ロングポーリング) ワークフロー。結果は最初の呼び出しで返される

図 4. 同期 (ロングポーリング) ワークフロー。ジョブの完了に向けて複数の呼び出しが自動的に行われる

最初の呼び出しは、設定済みの HTTP 動詞 (GET、POST、PUT、DELETE) を使用して行われ、関連するジョブが Orchestrator 内に作成されます。ジョブが正常に作成されると、システムは現在の呼び出しをブロックし、その間にジョブの完了を待機します。ジョブが完了すると、ブロックされていた呼び出しが解放され、ジョブの出力引数を含む応答が送り返されます。

If after a timeout period the job has not yet completed, the system responds with an HTTP status code 303 (See Other), redirecting to the status URI (via the Location header). You are expected to follow the status URI, which is blocked until the job is completed.

If the job is not completed after a timeout, you are yet again redirected to the status URI, thus creating a redirect loop. Upon successful completion of the job, the job result (output or error) is retrieved as part of the HTTP response.

既定では、認可用の有効なベアラー トークンがすべての呼び出しに含まれている必要があります。ただし、テナント設定オプションの [同期 API トリガーのリダイレクトに Authentication ヘッダーを要求] が選択されていない場合は、トリガーに対する最初の呼び出しでのみ Authentication ヘッダーが求められます。ステータス エンドポイントへの後続の呼び出しは、認可ヘッダーを設定せずに行うことができます。

この呼び出しモードで許可されているジョブの最長実行時間は 15 分間です。

JavaScript の例

この例では、同期 (ロングポーリング) 呼び出しモードを使用して、ブラウザーから API トリガーを介してジョブを開始する方法を示します。

const url = 'https://{yourDomain}/{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# の例

この例では、同期 (ロングポーリング) 呼び出しモードを使用して、C# ベースのアプリケーションから API トリガーを介してジョブを開始する方法を示します。

public async Task SyncExample()
{
    const string url = "https://{yourDomain}/{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.SeeOther)
    {
        // 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);
}