ホスト API

ホスト API は、アプリのさまざまな部分と YouTrack 間の通信をサポートする補助 API です。

ホスト API の使い方

ウィジェットが YouTrack に HTTP リクエストを送信したり、YouTrack API のいずれかを使用して YouTrack と通信したりする場合は、ウィジェットの HTML コードに、ウィジェットを YouTrack に登録するスクリプトを含める必要があります。

登録スクリプトの例を次に示します。

            <script type="module">
                const host = await YTApp.register();
                host.alert('Hello world');
            </script>
        

ウィジェットを登録すると、ホスト API を使用して YouTrack でアラートを送信したり、カスタム HTTP ハンドラーとして実装された関数を呼び出したりできるようになります。

ホスト API リファレンス

以下は、Host API がサポートするメソッドの一覧です。

警告

この方法を使用すると、アプリ内から YouTrack に警告メッセージを送信できます。

パラメーター	タイプ	説明	必須
`message`	文字列	警告メッセージのテキスト。	✓

このメソッドを使用するサンプルコードはこちらで確認できます。

                const host = await YTApp.register();
                host.alert('Hello world');
            

フェッチユートラック

このメソッドにより、アプリは YouTrack REST API を使用できるようになります。

パラメーター	タイプ	説明	必須
`relativeURL`	文字列	REST API エンドポイントへの相対 URL。	✓
`requestParams`	RequestParams	オプションのフェッチパラメーター。詳細については、以下の requestParams を参照してください。

パラメーター

タイプ

説明

必須

relativeURL

文字列

REST API エンドポイントへの相対 URL。

✓

requestParams

RequestParams

オプションのフェッチパラメーター。

詳細については、以下の requestParams を参照してください。

このメソッドを使用するサンプルコードはこちらで確認できます。

                const host = await YTApp.register();
                const user = await host.fetchYouTrack(`users/${YTApp.entity.id}?fields=id,login,name`);
            

オプションのクエリパラメーターを含むサンプルを次に示します。

                const ytResponse = await host.fetchYouTrack('users', {query: {fields: 'id,login,email'});
            

フェッチアプリ

このメソッドを使用すると、アプリはカスタム HTTP ハンドラーと通信し、そのメソッドを呼び出すことができます。fetchApp メソッドは fetchYouTrack メソッドに似ていますが、追加の scope パラメーターがあります。このパラメーターを使用すると、スコープエンドポイントまたはグローバルエンドポイントのどちらに要求を行うかを指定できます。

fetchApp メソッドは JSON を解析し、すぐに使用できる応答オブジェクトを返します。

パラメーター	タイプ	説明	必須
`relativeURL`	文字列	カスタム HTTP エンドポイントへの相対 URL。詳細については、HTTP ハンドラーを参照してください。	✓
`requestParams`	リクエストパラメーターと { スコープ: ブール値 }	オプションのフェッチパラメーター。詳細については、以下の requestParams を参照してください。このパラメーターでハンドラーのスコープを設定するオプションがあります。スコープを `global` に設定するには、空のオブジェクトを渡します。アクセスしようとしている HTTP ハンドラーのスコープが制限されている場合は、スコープを `true` に設定します。これにより、スコープエンティティがコンテキストからハンドラーで使用できるようになります。詳細については、スコープを参照してください。

パラメーター

タイプ

説明

必須

relativeURL

文字列

カスタム HTTP エンドポイントへの相対 URL。詳細については、HTTP ハンドラーを参照してください。

✓

requestParams

リクエストパラメーターと { スコープ: ブール値 }

オプションのフェッチパラメーター。詳細については、以下の requestParams を参照してください。

このパラメーターでハンドラーのスコープを設定するオプションがあります。スコープを global に設定するには、空のオブジェクトを渡します。

アクセスしようとしている HTTP ハンドラーのスコープが制限されている場合は、スコープを true に設定します。これにより、スコープエンティティがコンテキストからハンドラーで使用できるようになります。詳細については、スコープを参照してください。

このメソッドを使用するサンプルコードはこちらで確認できます。

                const host = await YTApp.register();
                const appResponse = await host.fetchApp('backend/demo', {scope: true});
            

クエリパラメーターを含む GET リクエストのサンプルを次に示します。

                const appResponse = await host.fetchApp('backend/demo', {query: {key: '12345', count: 20, filter: true});
            

本文を含む POST リクエストのサンプルを次に示します。

                const appResponse = await host.fetchApp('backend/demo', {method: 'POST', body: {test: 'test'}});
            

リクエストパラメーター

requestParams オブジェクトは基本的に、Fetch API でリクエストをカスタマイズするために使用される requestInit オブジェクトの拡張です。requestInit オブジェクトでサポートされる基本プロパティに加えて、requestParams は次の補足プロパティをサポートします。

プロパティ	説明
`query`	HTTP リクエストのクエリパラメーターとして使用されるキーと値のペアを含む JavaScript オブジェクト。例: const query = { key: '12345', shelterID: 'abc00', count: 20, animals: true };
`scope`	リクエストをスコープエンドポイントに送信するか、グローバルエンドポイントに送信するかを示すブールプロパティ。例: // appResponse is a parsed JSON: const appResponse = await host.fetchApp('backend/demo', {scope: true}); console.log('test', appResponse.test);

DASHBOARD_WIDGET および MARKDOWN 拡張ポイントを使用するアプリは、ウィジェットがダッシュボードまたはテキストフィールドに挿入されるたびに、特別な埋め込みコンポーネントを生成します。このコンポーネントは、ウィジェットがこれらの場所に表示されるデータを保存します。その結果、これらのウィジェットは、CustomWidgetAPILayer と呼ばれるより拡張された API によってサポートされます。

これらの拡張ポイントでサポートされている追加メソッドのリストを次に示します。

タイトルを設定する

setTitle(label: string, ?labelUrl: string): void

ウィジェットのヘッダーに表示されるテキストを設定します。labelUrl パラメーターに値が指定されている場合、テキストはターゲット URL へのリンクとして設定されます。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`label`	文字列	ウィジェットのタイトルとして表示される文字列。	✓
`labelURL`	文字列	ユーザーがウィジェットのタイトルをクリックしたときに開くターゲットページのアドレス。このオプションのパラメーターが指定されていない場合、ウィジェットのタイトルはテキストとしてのみ設定されます。

読み込みアニメーションを有効にする

setLoadingAnimationEnabled(isEnabled: boolean): void

ウィジェットの再ロードアイコンのイメージ回転アニメーションを切り替えます。ウィジェットがリモートサーバーからデータを取り込むときにこのメソッドを呼び出して、プロセスがバックグラウンドで実行されていることを示します。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`isEnabled`	Boolean	ウィジェットの再ロードアイコンを回転させるかどうかを決定します。	✓

設定モードに入る

enterConfigMode(): void

設定モードを起動します。構成モードのときは、ウィジェットの視覚表示が変わり、その設定をリフレッシュできることを示します。リフレッシュアイコンも非表示になります。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

終了構成モード

exitConfigMode(): void

設定モードを終了します。

エラーの設定

setError(e: Error): void

ウィジェットにエラー状態を設定し、エラーメッセージを表示したり、その他のエラー処理アクションを実行したりします。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`e`	エラー	エラーの詳細を含むエラーオブジェクト。	✓

クリアエラー

clearError(): void

ウィジェットで以前に設定されたエラー状態をクリアします。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

キャッシュを読み込む

readCache(): Promise<unknown>

以前にキャッシュに保存されたデータを読み取ります。キャッシュされたデータに解決される promise を返します。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

ストアキャッシュ

storeCache(data: unknown): Promise<Void>

任意のオブジェクトをクライアント側のキャッシュに保存します。このメソッドを使用して、入力されたデータをローカルに保存し、ウィジェットにすぐに表示してから、サーバーからリフレッシュします。データが正常に保存されたときに解決される promise を返します。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`data`	不明	キャッシュに保存するデータを指定します。	✓

読み取り構成

readConfig(): Promise<unknown>

ウィジェットの構成データを読み取ります。構成データに解決される Promise を返します。

構成オブジェクトのスキーマは、ウィジェットマニフェストの settingsSchemaPath プロパティで宣言する必要があります。宣言されていないペイロードは無視されます。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

ストア構成

storeConfig(config: unknown): Promise<Void>

ウィジェットの構成データを保存します。構成モードがアクティブな場合は、構成モードを終了します。

構成データが正常に保存されたときに解決される promise を返します。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`config`	不明	保存する構成データ。	✓

ダウンロードファイル

downloadFile(serviceID: string, relativeURL: string, requestParams: unknown, fileName?: string): Promise<void>

指定されたサービスからファイルをダウンロードします。

ファイルが正常にダウンロードされたときに解決される promise を返します。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`serviceID`	文字列	ファイルをダウンロードするサービスの ID。	✓
相対 URL	文字列	サービス内のファイルへの相対 URL パス。	✓
リクエストパラメーター	不明	リクエストに含めるパラメーター。	✓
ファイル名	文字列	ダウンロードするファイルの名前。指定しない場合は、サービスによってデフォルトの名前が提供される場合があります。

フェッチハブ

fetchHub(relativeURL: string, requestParams: RequestParams): unknown

YouTrack に接続されているか、YouTrack に組み込まれている Hub サービスからデータを取得します。fetch メソッドに似ていますが、Hub サービス用に特別に設計されています。

取得したデータを返します。戻り値の型は、サービスから取得された情報によって異なります。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`relativeURL`	文字列	URL を Hub サービス API エンドポイントに設定します。これは取得したいリソースへのパスです。URL はサーバーのホーム URL からの相対パスです。詳しくは Hub のドキュメント(英語)を参照してください。	✓
`requestParams`	RequestParams	リクエストに含めるオプションのパラメーター。

例:

CustomWidgetAPILayer.fetchHub('api/rest/users/me?fields=name,login,profile(avatar(url))')
                .then(response => console.log(response));

次の例は、POST リクエストでこのメソッドを使用する方法を示しています。

host.fetchHub('api/rest/users/me', {
                method: 'POST',
                body: {favoriteProjects: []}
                })
                .then(response => console.log(response));

警告

alert(...args: Parameters<(typeof AlertService)['addAlert']>): void

ページの左下隅にシステム警告を表示します。

これは、JetBrains リング UI コンポーネントライブラリの AlertService(英語) コンポーネントのラッパーです。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

パラメーター	タイプ	説明	必須
`args`	パラメーター	`AlertService` の `addAlert` メソッドに必要なパラメーター。	✓

例:

host.alert('Hello world', 'success', 5000)

removeWidget(): void

ユーザーインターフェースから埋め込まれたウィジェットを削除します。

DASHBOARD_WIDGET または MARKDOWN 拡張ポイントを使用するウィジェットでのみ使用できます。

最終更新日: 2024 年 11 月 7 日

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

ホスト API

ホスト API の使い方

ホスト API リファレンス

警告

フェッチユートラック

フェッチアプリ

リクエストパラメーター

カスタムウィジェット API リファレンス

タイトルを設定する

読み込みアニメーションを有効にする

設定モードに入る

終了構成モード

エラーの設定

クリアエラー

キャッシュを読み込む

ストアキャッシュ

読み取り構成

ストア構成

ダウンロードファイル

フェッチハブ

警告

ウィジェットを削除

関連ページ：