非同期関数

YouTrack ワークフロー API への呼び出しのほとんどは同期的に実行されます。スクリプトは結果を受け取り、現在の操作が処理されている間も同じスクリプトの実行を継続します。ワークフロールールでは、この同期処理は現在のワークフロートランザクションに属します。YouTrack がトランザクション内でワークフロールールの変更をどのように処理するかについては、トランザクションを参照してください。

非同期関数は、別途後続のステップを導入します。非同期関数は、asyncFunctions オブジェクト内で宣言された名前付き JavaScript 関数です。スクリプトは、ctx.invokeAsync() メソッドまたは非同期 HTTP メソッドを使用して名前で非同期関数をスケジュールし、YouTrack は現在のトランザクションが完了した後にその関数を実行します。

非同期関数は、開始する操作をブロックしてはならないタスクに使用します。一般的な使用例としては、外部サービスへのリクエスト送信、応答の処理、更新の遅延、繰り返し発生する変更のデバウンスなどが挙げられます。

非同期関数は、on-change、アクション、on-schedule ワークフロールール、アプリ HTTP ハンドラー、およびカスタム MCP ツールでサポートされています。この記事の例ではワークフロールールを使用していますが、基本的なパターンはサポートされているすべてのスクリプトタイプで共通です。

ルールサンプル

以下のワークフロールールは、古い課題の概要と新しい課題の概要を保存し、2 秒後にコメントを追加する非同期関数をスケジュールします。

            const entities = require('@jetbrains/youtrack-scripting-api/entities');

            exports.rule = entities.Issue.onChange({
              title: 'Comment on summary changes later',
              guard: (ctx) => ctx.issue.isChanged('summary'),
              action: (ctx) => {
                // Save values that the async function needs later.
                ctx.store('previousSummary', ctx.issue.oldValue('summary') || '');
                ctx.store('updatedSummary', ctx.issue.summary);

                // Schedule the async function to run two seconds later.
                ctx.invokeAsync('addSummaryChangeComment', 2000);
              },
              asyncFunctions: {
                addSummaryChangeComment: (ctx) => {
                  // Load values from the async execution context.
                  const previousSummary = ctx.load('previousSummary');
                  const updatedSummary = ctx.load('updatedSummary');

                  ctx.issue.addComment(
                    'Summary changed from "' + previousSummary + '" to "' + updatedSummary + '".'
                  );
                }
              }
            });
        

概念と範囲

非同期関数は、サポートされているスクリプトの種類に関わらず、同じスケジューリングパターンを使用します。利用可能なコンテキスト、実行タイミング、制限、関連するオブジェクトとメソッドは、非同期処理が開始される場所によって異なります。

サポートされているスクリプトの種類

非同期関数は、以下のスクリプトタイプで使用できます。

スクリプトタイプ	ノート
変更時、アクション、および on-schedule ワークフロールール	非同期関数は、`ctx.issue`、`ctx.currentUser`、ルール要件を含む、ルールアクションと同じワークフロールールコンテキストを使用します。
アプリの HTTP ハンドラー	非同期関数は、`issue`、`project`、`article`、`user` または `global` スコープを持つアプリ HTTP ハンドラーエンドポイントからスケジュールできます。非同期 HTTP 呼び出しからの応答の処理の詳細については、取引完了後に外部サービスを呼び出すを参照してください。
カスタム MCP ツール	非同期関数は、カスタム MCP ツールアクションからスケジュールできます。非同期関数のコンテキストはカスタム MCP ツールコンテキストに従うため、`ctx.arguments` は提供されますが、`ctx.issue`、`ctx.article`、`ctx.user` は提供されません。

非同期実行 Flow

スクリプトが非同期処理をスケジュールした後、YouTrack はフォローアップ機能を別のステップとして実行します。

スケジューリング機能は、ctx.invokeAsync() メソッドまたは非同期関数の名前を持つ非同期 HTTP メソッドを呼び出します。
取引が正常に完了した場合、YouTrack は後で同じユーザーとして後続作業を開始します。
フォローアップ機能は、作業をスケジュールしたスクリプトの種類に基づいて、新しい ctx オブジェクトを受け取ります。
後続関数がスケジューリング関数から値を必要とする場合、スケジューリング関数はそれらを ctx.store() に格納し、後続関数は ctx.load() を使用して読み取ります。

非同期処理のためのオブジェクトとメソッド

非同期関数は、タスクに応じて異なるオブジェクトやメソッドとやり取りします。スクリプトは、ctx.invokeAsync() メソッドを使用して名前付き非同期関数をスケジュールできます。非同期 HTTP 呼び出しの場合、スクリプトは HTTP モジュールのメソッドと非同期 HTTP レスポンスコンテキストも使用します。

スクリプトオブジェクト

asyncFunctions オブジェクトは、非同期関数をスケジュールするスクリプトオブジェクトと同じオブジェクト内で、名前付き非同期関数を宣言します。

詳しくは、非同期関数を宣言してスケジュールするを参照してください。

コンテキストメソッド

ctx オブジェクトは、非同期関数のスケジュール設定や、非同期ステップ間で一時的な状態を渡すためのメソッドを提供します。

ctx.invokeAsync() は、名前付き非同期関数をスケジュールします。詳細については、非同期関数を宣言してスケジュールするを参照してください。
ctx.store() は非同期実行コンテキストに値を保存します。詳細については、非同期呼び出し間で状態を共有するを参照してください。
ctx.load() は保存された値を読み取ります。詳細については、非同期呼び出し間で状態を共有するを参照してください。

HTTP モジュールメソッド

@jetbrains/youtrack-scripting-api/http モジュールは、HTTP リクエストを後で送信するための非同期 HTTP メソッドを提供します。

postAsync()、getAsync()、その他の非同期 HTTP メソッドは、外部サービスの応答を名前付き非同期関数に渡します。詳細については、取引完了後に外部サービスを呼び出すを参照してください。

非同期 HTTP レスポンスコンテキスト

ctx.response プロパティには、非同期 HTTP メソッドに渡される非同期関数内の外部サービス応答が含まれます。

詳しくは、取引完了後に外部サービスを呼び出すを参照してください。

非同期関数の操作

非同期の後続処理は、2 つの要素に依存します。1 つは、関数 YouTrack が後で実行される必要があること、もう 1 つはその関数が実行されるときに利用可能である必要がある値です。

非同期関数を宣言してスケジュールする

非同期関数は、処理を開始するスクリプトオブジェクトと同じスクリプトオブジェクト内の asyncFunctions オブジェクトで宣言します。asyncFunctions オブジェクトは、スクリプトオブジェクトの最上位プロパティです。スクリプトの種類に応じて、action、handle、execute などのプロパティの隣に配置します。

asyncFunctions オブジェクトは、関数名と JavaScript 関数のマッピングです。これらの関数名のいずれかを ctx.invokeAsync() メソッドまたは非同期 HTTP メソッドに渡してください。インラインコールバックはサポートされていません。

ctx.invokeAsync() メソッドは、現在のトランザクションが完了した後に実行されるように、指定された非同期関数をスケジュールします。この非同期関数からは値は返されません。

ctx.invokeAsync() メソッドは、以下のパラメーターを受け入れます。

パラメーター	説明	必須
`functionName`	`asyncFunctions` オブジェクト内のキーと一致する文字列。	✓
`delay`	非同期実行までの遅延時間（ミリ秒）。デフォルト値: `0`
`deduplicationKey`	YouTrack が保留中の非同期呼び出しをより新しいものに置き換えることを可能にする文字列キー。繰り返しスケジュールされた処理によって保留中の呼び出しを解消する必要がある場合に使用します。たとえば、同じ課題に対する頻繁な更新処理によるデバウンス（不正な呼び出しの回避）を行う際に使用します。同じスクリプト構成に対して同じキーを持つ別の保留中の呼び出しが存在する場合、YouTrack は古い呼び出しを削除し、新しい呼び出しを新しい遅延時間でスケジュールします。ワークフロー規則では、重複排除のスコープは特定のプロジェクトに紐づけられた特定の規則です。別の規則または別のプロジェクトに同じキーがあっても、保留中の呼び出しは置き換えられません。

パラメーター

説明

必須

functionName

asyncFunctions オブジェクト内のキーと一致する文字列。

✓

delay

非同期実行までの遅延時間（ミリ秒）。

デフォルト値: 0

deduplicationKey

YouTrack が保留中の非同期呼び出しをより新しいものに置き換えることを可能にする文字列キー。

繰り返しスケジュールされた処理によって保留中の呼び出しを解消する必要がある場合に使用します。たとえば、同じ課題に対する頻繁な更新処理によるデバウンス（不正な呼び出しの回避）を行う際に使用します。

同じスクリプト構成に対して同じキーを持つ別の保留中の呼び出しが存在する場合、YouTrack は古い呼び出しを削除し、新しい呼び出しを新しい遅延時間でスケジュールします。ワークフロー規則では、重複排除のスコープは特定のプロジェクトに紐づけられた特定の規則です。別の規則または別のプロジェクトに同じキーがあっても、保留中の呼び出しは置き換えられません。

保存値は、後続処理のための短期的なデータです。これらは非同期呼び出しチェーンにスコープされ、チェーンが完了するとクリーンアップされます。長期にわたるデータには、アプリ設定または YouTrack エンティティを使用してください。

以下のメソッドは、保存された値を保存および読み取ります。

ctx.store(key, value)

ctx.store() メソッドは、スクリプトが非同期関数または非同期 HTTP 呼び出しをスケジュールする前に、非同期実行コンテキストに値を保存します。

保存された値は、同じスクリプトの実行中に非同期関数または非同期 HTTP 呼び出しがスケジュールされた場合にのみ保持されます。

例:

                    // Save a value for the async function.
                    ctx.store('commentText', 'Summary changed to: ' + ctx.issue.summary);
                    ctx.invokeAsync('addSummaryComment');
                

パラメーター	説明
`key`	格納された値を識別するための文字列識別子。
`value`	プリミティブ値 `null`、または YouTrack エンティティへの参照。

ctx.load(key)

ctx.load() メソッドは、非同期関数内で ctx.store() で保存された値を読み取ります。指定されたキーが保存されていない場合は、null を返します。

格納されたエンティティ参照は、YouTrack エンティティオブジェクトに解決されます。

例:

                    // Read a value saved in the scheduling function.
                    const commentText = ctx.load('commentText');
                

パラメーター	説明
`key`	読み込む保存値の文字列識別子。

非同期 HTTP 呼び出しとチェーン

非同期 HTTP メソッドを使用すると、スクリプトはトランザクションが完了した後にのみ YouTrack が送信する HTTP リクエストをスケジュールできます。非同期関数は別のステップをスケジュールすることもできるため、スクリプトは開始した操作をブロックすることなく、順序付けられた後続処理を実行できます。

取引完了後に外部サービスを呼び出す

@jetbrains/youtrack-scripting-api/http モジュールは、HTTP リクエストメソッドの非同期バリアント（doAsync、getAsync、postAsync、putAsync、patchAsync、deleteAsync）を提供します。

これらの非同期 HTTP メソッドは、現在のスクリプト実行中に HTTP リクエストの送信をスケジュールします。YouTrack は、現在のトランザクションが完了した後にリクエストを送信します。最後の引数として非同期関数の名前を渡してください。YouTrack は外部サービスからの応答を受信すると、その関数を呼び出し、応答を ctx.response プロパティとして公開します。

非同期 HTTP メソッドは、スケジューリング関数にレスポンスを返さず、遅延実行もサポートしていません。外部レスポンス処理ロジックは、名前付き非同期関数内に記述してください。

以下のワークフロールールは、HTTP リクエストを送信し、非同期関数でレスポンスを処理します。

            const entities = require('@jetbrains/youtrack-scripting-api/entities');
            const http = require('@jetbrains/youtrack-scripting-api/http');

            exports.rule = entities.Issue.onChange({
              title: 'Notify external service after transaction completion',
              guard: (ctx) => ctx.issue.isChanged('State'),
              action: (ctx) => {
                const connection = new http.Connection('https://api.example.com');
                connection.addHeader('Content-Type', 'application/json');

                // Schedule YouTrack to send the HTTP request after this transaction is complete.
                connection.postAsync(
                  '/issue-events',
                  null,
                  JSON.stringify({id: ctx.issue.id, state: ctx.issue.fields.State.name}),
                  'onExternalResponse'
                );
              },
              asyncFunctions: {
                onExternalResponse: (ctx) => {
                  // The ctx.response property contains the external service response.
                  if (ctx.response.isSuccess) {
                    ctx.issue.addComment('External service accepted the update.');
                  } else {
                    console.warn('External service failed: ' + ctx.response.body);
                  }
                }
              }
            });
        

ワークフロー規則における HTTP リクエストの詳細については、JavaScript ワークフローでの REST API メソッドの使用を参照してください。

チェーン非同期呼び出し

非同期関数は、次の非同期ステップをスケジュールできます。後続の処理を順番に実行する必要がある場合、たとえば、ある非同期関数がデータを準備し、次の非同期関数がそれを外部サービスに送信する場合などは、非同期呼び出しを連鎖させて使用します。

各スクリプト関数の実行では、非同期関数または非同期 HTTP 呼び出しを 1 つだけスケジュールできます。デフォルトのチェーンの最大実行回数は 10 回です。

            const entities = require('@jetbrains/youtrack-scripting-api/entities');
            const http = require('@jetbrains/youtrack-scripting-api/http');

            exports.rule = entities.Issue.onChange({
              title: 'Send issue update in async steps',
              guard: (ctx) => ctx.issue.isChanged('State'),
              action: (ctx) => {
                const state = ctx.issue.fields.State ? ctx.issue.fields.State.name : '';

                // Schedule the first async step for after this transaction is complete.
                ctx.store('stateName', state);
                ctx.invokeAsync('preparePayload');
              },
              asyncFunctions: {
                preparePayload: (ctx) => {
                  // This async function can schedule the next step in the chain.
                  const payload = JSON.stringify({
                    issueId: ctx.issue.id,
                    state: ctx.load('stateName')
                  });

                  ctx.store('payload', payload);
                  ctx.invokeAsync('sendPayload');
                },
                sendPayload: (ctx) => {
                  const connection = new http.Connection('https://api.example.com');
                  connection.addHeader('Content-Type', 'application/json');

                  // The async HTTP response handler is the next step in the same chain.
                  connection.postAsync('/issue-events', null, ctx.load('payload'), 'onServiceResponse');
                },
                onServiceResponse: (ctx) => {
                  // This async response handler runs when YouTrack receives the external response.
                  if (!ctx.response.isSuccess) {
                    console.warn('External service failed: ' + ctx.response.body);
                  }
                }
              }
            });
        

実行動作と制限

非同期関数は、実行が遅延する後続処理であり、処理のスケジュール設定や連鎖に影響を与える制限があります。これらの制限は、サポートされているすべてのスクリプトタイプに適用されます。

アスペクト	詳細
トランザクションのタイミング	スケジュールされた非同期関数は、それをスケジュールしたトランザクションが正常に完了した後にのみ開始されます。
ユーザー	非同期関数は、非同期処理をスケジュールしたユーザーと同じユーザーとして実行されます。
トランザクションの範囲	各非同期関数は、新しいトランザクション内で実行されます。
実行ごとのスケジューリング	各スクリプト関数の実行では、1 つの非同期関数または 1 つの非同期 HTTP 呼び出しをスケジュールできます。
遅延	スケジュールされた非同期関数の最大遅延期間は 7 日間です。
チェーンの長さ	非同期関数は、別の非同期関数または非同期 HTTP 呼び出しをスケジュールして、後続処理のチェーンを作成できます。デフォルトのチェーンの最大長は、10 個の非同期実行です。
エラー処理	非同期関数がエラーをスローした場合、YouTrack はその呼び出しにおける残りの非同期呼び出しチェーンを停止します。
クリーンアップ	2 日以上経過しても使用されていない非同期実行コンテキストは、自動的にクリーンアップされます。

2026 年 7 月 06 日

YouTrack および Hub ヘルプの開発者ポータル

非同期関数

ルールサンプル

概念と範囲

サポートされているスクリプトの種類

非同期実行 Flow

非同期処理のためのオブジェクトとメソッド

非同期関数の操作

非同期関数を宣言してスケジュールする

非同期 HTTP 呼び出しとチェーン

取引完了後に外部サービスを呼び出す

チェーン非同期呼び出し

実行動作と制限

関連ページ：

非同期関数

ルールサンプル

概念と範囲

サポートされているスクリプトの種類

非同期実行 Flow

非同期処理のためのオブジェクトとメソッド

非同期関数の操作

非同期関数を宣言してスケジュールする

非同期呼び出し間で状態を共有する

非同期 HTTP 呼び出しとチェーン

取引完了後に外部サービスを呼び出す

チェーン非同期呼び出し

実行動作と制限

関連ページ：