HTTP ハンドラー

HTTP ハンドラーを使用すると、カスタム HTTP エンドポイントから YouTrack データにアクセスできるようになります。これらのハンドラーは REST API を拡張し、クライアントは特定のウィジェットのフロントエンドコードだけでなく、他の YouTrack REST API エンドポイントと同様にこれらのエンドポイントを呼び出すことができます。つまり、HTTP ハンドラーを使用して、サードパーティのサービスからアクセスできる Webhook をプロビジョニングできます。

YouTrack は、JavaScript で記述されたカスタム HTTP ハンドラーをサポートします。現在の YouTrack JavaScript 実装は、最新の ECMAScript 仕様と互換性があります。

サンプル HTTP ハンドラー

以下は、カスタム HTTP ハンドラーを実装するためのサンプルスクリプトです。

exports.httpHandler = {
    endpoints: [
        {
            scope: "issue",
            method: "GET",
            path: "demo",
            permissions: ['READ_ISSUE', 'READ_USERGROUP'],
            handle: function (ctx) {
                ctx.response.json({message: "Hello World"});
            }
        }
    ]
}
        

HTTP ハンドラー API

これは、カスタム HTTP ハンドラーを実装するスクリプトのリファレンスです。

各スクリプトは、1 つの HTTP ハンドラーを exports.httpHandler プロパティにエクスポートします。HTTP ハンドラーは、endpoints の配列を含むオブジェクトとして宣言されます。

エンドポイント

各エンドポイントには次のプロパティが含まれます。

プロパティ	説明
`scope`	エンドポイントのスコープエンティティ。スコープを設定すると、スコープエンティティが `handle` 関数のコンテキストで使用できるようになります。 YouTrack は次のスコープをサポートしています: `issue`、`project`、`article`、`user`、`global` デフォルト値: `global` 詳細については、スコープを参照してください。
`method`	エンドポイントが実装する HTTP メソッド。 YouTrack は、GET、POST、PUT、DELETE メソッドをサポートします。
`path`	エンドポイントにアクセスするための相対パス。アプリでエンドポイントを使用するには、このパスをハンドラーファイルの名前に追加し、`host.fetchApp()` を介してエンドポイントを呼び出します。サンプル: `const appResponse = await host.fetchApp('backend/demo', {scope: true});`
`permissions`	指定されたメソッドを使用してエンドポイントを呼び出すときに確認する権限のリスト。エンドポイントにアクセスしようとするユーザーが指定された権限の少なくとも 1 つを持っている限り、要求は承認されます。権限は配列としてリストされます。各権限はキーを使用して参照されます。権限とキー値の完全なリストについては、アプリの権限を参照してください。
`handle`	誰かが指定されたメソッドを使用してエンドポイントを呼び出したときに YouTrack が呼び出す関数。

スコープ

ここでは、HTTP エンドポイントで使用可能な scope 値について詳しく知ることができます。

スコープを設定すると、スコープエンティティが handle 関数のコンテキストで使用できるようになります。

スコープを明示的に設定しない場合、デフォルト値は global になります。

スコープ	説明	関連する拡張ポイント
`issue`	`ctx.issue` エンティティを `handle` 関数のコンテキストに追加します。	`ISSUE_ABOVE_ACTIVITY_STREAM` `ISSUE_BELOW_SUMMARY` `ISSUE_FIELD_PANEL_LAST` `ISSUE_FIELD_PANEL_FIRST` `ISSUE_OPTIONS_MENU_ITEM`
`project`	`ctx.project` エンティティを `handle` 関数のコンテキストに追加します。	`HELPDESK_CHANNEL` `PROJECT_SETTINGS`
`article`	`ctx.article` エンティティを `handle` 関数のコンテキストに追加します。	`ARTICLE_OPTIONS_MENU_ITEM`
`user`	`ctx.user` エンティティを `handle` 関数のコンテキストに追加します。	`USER_CARD` `USER_PROFILE_SETTINGS`
`global`	デフォルトのスコープ。	このスコープを持つエンドポイントは、すべてのフロントエンド拡張機能からアクセスできます。

HTTP リクエスト

HTTP リクエストは、エンドポイントが受信するオブジェクト (ctx.request) です。

Properties

HTTP リクエストオブジェクトのプロパティを次に示します。

プロパティ	タイプ	説明
`body`	文字列	リクエスト本体。
`bodyAsStream`	オブジェクト	リクエスト本体のバイトストリーム表現。
`headers`	Array。<{ 名前: 文字列、値: 文字列 }>	リクエストヘッダーのコレクション。
`path`	文字列	エンドポイントへの相対パス。`endpoint.path` に等しい。
`fullPath`	文字列	エンドポイントへの完全なパス。
`method`	文字列	リクエストが使用した HTTP メソッド。GET、POST、PUT、DELETE のいずれかになります。
`parameterNames`	配列 .<文字列>	URL パラメーター名の配列

関数

HTTP リクエストを処理するために使用できる関数を次に示します。

プロパティ	戻りの型	説明
`json()`	JSON	リクエスト本文を JSON 形式で返します。
`getParameter(name)`	文字列	名前で URL パラメーターを返します。
`getParameters(name)`	配列 .<文字列>	すべての URL パラメーターを名前で文字列の配列として返します。

HTTP レスポンス

HTTP 応答は、クライアントからの要求に応じてハンドラーが返すオブジェクト (ctx.response) です。

Properties

HTTP 応答オブジェクトのプロパティを次に示します。

プロパティ	タイプ	説明
`body`	文字列	レスポンス本文。処理中に例外が発生した場合、レスポンス本文は空になります (`null`)。
`bodyAsStream`	オブジェクト	レスポンス本文のバイトストリーム表現。処理中に例外が発生した場合、プロパティは空になります (`null`)。
`code`	数	応答に割り当てられる HTTP ステータスコード。処理中に例外が発生した場合、プロパティは空になります。デフォルトは 200 です。

関数

HTTP 応答を操作するために使用できる関数を次に示します。

機能	戻り値の型	説明
`json(object)`		ハンドラーがクライアントに返す応答に `Content-Type: application/json` HTTP ヘッダーを追加します。応答は JSON 文字列の形式で表示されます。
`text(string)`	文字列	ハンドラーがクライアントに返す応答に `Content-Type: text/plain` HTTP ヘッダーを追加します。応答は文字列の形式で表示されます。
`addHeader(header, value)`	レスポンスオブジェクト	この関数は、レスポンスに HTTP ヘッダーを追加します。値として `null` を渡すと、対応するヘッダーがレスポンスから削除されます。同じ名前のヘッダーを複数渡すと、最後のヘッダーのみが保持されます。

要件

HTTP ハンドラーオブジェクトに追加の要件を含めることができます。HTTP ハンドラーオブジェクトには、スクリプトの要件を定義するために使用できる requirements フィールドがあります。

ワークフローコンテキストにおける YouTrack の JavaScript スクリプトの要件の動作の詳細については、要件を参照してください。

カスタム REST エンドポイントへのアクセス

カスタム REST エンドポイントを呼び出すと、対応する HTTP ハンドラーが呼び出されます。使用されるエンドポイントは、ハンドラーに割り当てられたスコーププロパティに基づきます。

スコープ	URL
`issue`	<ホスト>/api/issues/<issueId>/extensionEndpoints/app/handler/endpoint
`article`	<ホスト>/api/articles/<記事 ID>/extensionEndpoints/app/handler/endpoint
`project`	<ホスト>/api/admin/projects/<プロジェクト ID>/extensionEndpoints/app/handler/endpoint
`user`	<ホスト>/api/users/<ユーザー ID>/extensionEndpoints/app/handler/endpoint
`global`	<ホスト>/api/extensionEndpoints/app/handler/endpoint

アプリに合わせて次の変数を設定します。

app — アプリの名前。
handler — .js ファイル拡張子のない、アプリパッケージ内の HTTP ハンドラースクリプトを含むファイルの名前。
endpoint — 宣言からのパス。例: "path": "/endpoint"

各 API リクエストには、スコープエンティティと同じ権限が必要です。例: エンドポイント /api/issues/DEMO-1/extensionEndpoints/app/handler/endpoint には、ID DEMO-1 の課題にアクセスする権限を持つすべてのユーザーがアクセスできます。グローバルエンドポイントには、ゲストアカウントを除くすべてのユーザーがアクセスできます。

最終更新日: 2025 年 3 月 11 日

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

HTTP ハンドラー

サンプル HTTP ハンドラー

HTTP ハンドラー API

エンドポイント

スコープ

HTTP リクエスト

Properties

関数

HTTP レスポンス

Properties

関数

要件

カスタム REST エンドポイントへのアクセス

関連ページ：