呼び出しモードの説明

Orchestrator で HTTP 経由でのジョブ実行を作成および追跡するための API トリガー呼び出しモードの概要。

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

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

この問題を解決するために、HTTP プロトコルを使用して複数の呼び出しモードをモデル化しました。これらのモードは、標準のHTTPメソッド、ステータス コード、ヘッダーに依存して、システム内のジョブを作成および監視し、その結果を取得します。このため、接続を不必要に開いたままにすることがありません。

ここで提案している呼び出しモードには、それぞれ長所と短所があるため、ご自身の連携のニーズに最適なモードを選択してください。ただし、セキュリティで保護された通信を確保するために、各呼び出しでベアラー トークンを通じた適切な認証が求められることにご注意ください。

重要:

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

非同期ポーリング

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

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

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

ジョブが作成されたら、定期的にステータスをポーリングする必要があります。このポーリング プロセス中は、ジョブが実行されている限り、ステータス URI へ GET 要求を送信するたびに、HTTP ステータス コード 200 (OK) が返されます。ジョブが完了すると、ステータス URI への直後の GET 要求によって HTTP ステータス コード 303 (See Other) が返され、Location ヘッダーによって出力 URI にリダイレクトされます。

ジョブの結果 (出力またはエラー) を取得するには、出力 URI に従う必要があります。

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

JavaScript の例

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

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

const url = '{AutomationCloudURL}/{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 = "{AutomationCloudURL}/{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 = '{AutomationCloudURL}/{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 = "{AutomationCloudURL}/{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 内に作成されます。ジョブが正常に作成されると、システムは現在の呼び出しをブロックし、その間にジョブの完了を待機します。ジョブが完了すると、ブロックされていた呼び出しが解放され、ジョブの出力引数を含む応答が送り返されます。

タイムアウト期間が経過してもジョブが完了していない場合、システムは HTTP ステータス コード 303 (See Other) で応答し、Location ヘッダーによってステータス URI にリダイレクトします。ユーザーはステータス URI に従うことが期待されます。これはジョブが完了するまでブロックされます。

タイムアウト後にジョブが完了しない場合は、ステータス URI に再度リダイレクトされるため、リダイレクト ループが作成されます。ジョブが正常に完了すると、ジョブの結果 (出力またはエラー) が HTTP 応答の一部として取得されます。

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

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

JavaScript の例

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

const url = '{AutomationCloudURL}/{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 = "{AutomationCloudURL}/{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);
}