JetBrains Space ヘルプ

リンク展開

デフォルトでは、ユーザーがチャットチャネルに外部リンクを投稿すると、Space はリンクを展開します。つまり、リンクの背後にページのプレビューが表示されます。Space は、チャットメッセージだけでなく、ドキュメント、課題の説明、コミットとコードレビューのタイトルでもリンク展開をサポートします。

Space がリンクプレビューを構築できるようにするには、リンクの背後にあるページが次の要件を満たしている必要があります。

  • ページでは、ソーシャルメタタグでプレビュー情報を提供する必要があります。

  • ページは公開されている必要があり、認証は必要ありません。

ページが要件を満たしていない場合、Space はプレビューを表示できません。このような場合、対応する外部システムで認証し、必要なコンテンツを取得して、そのコンテンツを Space に提供するアプリケーションを作成できます。

現在、Space は添付ファイルのプレビューのみをサポートしています。添付ファイルのプレビューは、ページへのリンクを含むチャットメッセージの隣にあるページコンテンツの断片です。リンクがドキュメントまたは課題の説明の一部である場合、Space はリンクのツールチップにプレビューを表示します。添付ファイルのプレビューを提供するには、アプリケーションに Unfurl.App.ProvideAttachment 権限が必要です。

Space 展開キュー

展開を機能させるには、ユーザーが外部リンクを投稿するたびに、Space が何らかの方法でアプリケーションに通知する必要があります。投稿されたリンクごとに、Space はアプリケーションに短い汎用通知を送信し、リンクデータ (ユーザー ID、リンク URL など) を特別なキューに保存します。特定のリンク (つまり、キュー項目) 上のデータを取得するには、アプリケーションは API 呼び出しを使用してキューにクエリを実行する必要があります。キューアイテムの有効期間は 30 分です。

このアプローチにより、ネットワークのワークロードが軽減され、一時的な停止中にアプリケーションが未処理のリンクのリストを失うことがなくなります。

キュー項目は、次のプロパティを持つ ApplicationUnfurlQueueItem タイプのインスタンスです。

  • etag: long は、アプリケーションがキュー内の位置を追跡するのに役立つエンティティタグです。これは、新しいアイテムごとに増加する固有の番号です。アプリケーションは、この番号を永続ストレージに保存する必要があります。

  • id: string は、アイテムの一意の文字列識別子です。これを使用して、Space API にコールバックしてコンテンツを提供したり、認証を要求したりするときにアイテムを識別します。

  • target: string は掲載リンクの URL です。

  • context: ApplicationUnfurlContext は、チャットメッセージ、ブログ記事、ドキュメント、コードレビュータイトル、git コミットメッセージ、課題の説明など、リンクが投稿された Space 内の正確な場所に関する情報を提供します。

  • authorUserId: ProfileIdentifier.Id はリンクを投稿したユーザーの ID です。ユーザーを識別できない場合、たとえば、コミットをプッシュしたユーザーが現在の組織に属していない場合は、null を返します。

新しいアイテムがキューに表示されると、Space は NewUnfurlQueueItemsPayload タイプのペイロードを使用して通知を送信します。ペイロード自体には、アイテムに関する情報は含まれません。通知を受信すると、アプリケーションは applications/unfurls/queue Space API エンドポイントを呼び出してキューをポーリングする必要があります。また、アプリケーションが使用できない間に一部のキュー項目が失われる可能性があるため、アプリケーションは開始直後にキューをポーリングすることをお勧めします。

キューには大量のアイテムが含まれる可能性があるため、バッチでリクエストする必要があります。例: これは、etag =50 のアイテムから始まる 100 個のアイテムのバッチを取得する方法です。

import space.jetbrains.api.runtime.resources.applications import space.jetbrains.api.runtime.types.NewUnfurlQueueItemsPayload // variable that stores the etag of the last processed item // in real application, it must be stored in a persistent storage private var lastEtag: Long? = null when (val payload = readPayload(body)) { // ... is NewUnfurlQueueItemsPayload -> { // poll the link queue val queueApi = spaceClient.applications.unfurls.queue // as the queue may contain many items, get items in batches var queueItems = queueApi.getUnfurlQueueItems(lastEtag, batchSize = 100) while (queueItems.isNotEmpty()) { queueItems.forEach { item -> // generate preview for each item // ... } // get ETag of the last processed item lastEtag = queueItems.last().etag queueItems = queueApi.getUnfurlQueueItems(lastEtag, batchSize = 100) } } }
GET https://mycompany.jetbrains.space/api/http/applications/unfurls/queue?fromEtag=50&batchSize=100 Authorization: Bearer <here-goes-auth-token> Accept: application/json

外部システムからアクセストークンを取得する

リンクプレビューを構築するには、アプリケーションはリンクの背後にある外部ページのコンテンツをフェッチする必要があります。この外部システムが認証を必要とする場合、アプリケーションはまず、リンクを投稿したユーザーに代わってシステム内で認証を行う必要があります。

  1. ユーザー認証を要求するには、/api/http/applications/unfurls/queue/request-external-auth API 呼び出しを使用します。呼び出しでは、アプリケーションはユーザーが認証する手段を提供する必要があります。この目的のために、Space メッセージコンストラクターと NavigateUrlAction 型のインスタンスを使用できます。このアクションは、アプリケーションのエンドポイントである必要がある指定された URL にユーザーを移動します。

    例: これは、https://myapplication.url/oauth?user=space-user-id につながる単一の認証するボタンを含むメッセージを作成する方法です。

    spaceClient.applications.unfurls.queue.requestExternalSystemAuthentication( item.id, unfurl { section { text("Authenticate in Slack to get link previews in Space") controls { button( "Authenticate", NavigateUrlAction( "https://myapplication.url/oauth?user=$spaceUserId", // BackUrl lets the app return the user back to the // page where they clicked the button withBackUrl = true, openInNewTab = false ) ) } } } )
    POST https://mycompany.jetbrains.space/api/http/applications/unfurls/queue/request-external-auth Authorization: Bearer here-goes-access-token Accept: application/json Content-Type: application/json { "queueItemId": "here-goes-item-id", "message": { "style": "PRIMARY", "sections": [ { "className": "MessageSectionV2", "elements": [ { "className": "MessageControlGroup", "elements": [ { "className": "MessageButton", "text": "", "style": "REGULAR", "action": { "className": "NavigateUrlAction", "url": "https://myapplication.url/oauth?user=here-goes-space-user-id", "withBackUrl": true, "openInNewTab": false } } ] } ] } ] } }
  2. アプリケーションに、認証呼び出しを処理するエンドポイント (この例では /oauth) を追加します。エンドポイントは、ユーザーを外部サービスの OAuth エンドポイントにリダイレクトする必要があります。ユーザーがシステムで認証された後、システムはアプリケーションのアクセストークンを発行する必要があります。

    この機能の正確な実装は、外部システムに実装されている OAuth フローによって異なります。このガイドでは一般的な手順は提供しません。Slack メッセージを展開する方法については、チュートリアルで例を見つけることができます。

展開されたコンテンツを Space に送信する

アプリケーションが外部システムで認証され、必要なコンテンツを取得した後、このコンテンツを準備して Space に送信できます。これを行うには、applications/unfurls/queue/content Space API エンドポイントに POST リクエストを送信します。リクエストには、次のデータを含む ApplicationUnfurl クラスのインスタンスが含まれている必要があります。

  • queueItemID: string は、元のメッセージの展開キュー ID です。

  • content: ApplicationUnfurlContent はメッセージの内容です。次の 2 種類のコンテンツが可能です。

    • ApplicationUnfurlContent.Message は、メッセージコンストラクター DSL を使用して構築されたメッセージです。

    • ApplicationUnfurlContent.Image はイメージです。Space は、プレビューを処理するときにイメージをダウンロードして保存します。外部サーバー上のイメージを更新しても、Space のプレビューは更新されません。

例:

// Message val content: ApplicationUnfurlContent.Message = unfurl { MessageOutlineV2( elements = listOf( MessageIcon( icon = ApiIcon("bug"), style = MessageStyle.PRIMARY ), MessageInlineText( text = "Title goes here", style = null ) ) ) section { MessageSectionV2( elements = listOf( MessageText( accessory = null, style = MessageStyle.PRIMARY, size = null, content = "Here goes unfurled content." ) ), style = null, textSize = null ) } } spaceClient.applications.unfurls.queue.postUnfurlsContent( listOf(ApplicationUnfurl("here-goes-item-id", content)) )
// Image spaceClient.applications.unfurls.queue.postUnfurlsContent( unfurls = listOf(ApplicationUnfurl( // item represents a queue item queueItemId = item.id, content = ApplicationUnfurlContent.Image( icon = null, title = "Title goes here", url = "https://externalservice.url/image.png" ) )) )
# Message POST https://mycompany.jetbrains.space/api/http/applications/unfurls/queue/content Authorization: Bearer here-goes-access-token Accept: application/json Content-Type: application/json { "unfurls": [ { "queueItemId": "here-goes-item-id", "content": { "className": "ApplicationUnfurlContent.Message", "style": "PRIMARY", "outline": { "className": "MessageOutlineV2", "elements": [ { "className": "MessageIcon", "icon": { "icon": "bug" }, "style": "PRIMARY" }, { "className": "MessageInlineText", "text": "Title goes here" } ] }, "sections": [ { "className": "MessageSectionV2", "elements": [ { "className": "MessageText", "style": "PRIMARY", "content": "Here goes unfurled content." } ] } ] } } ] }
# Image POST https://mycompany.jetbrains.space/api/http/applications/unfurls/queue/content Authorization: Bearer here-goes-access-token Accept: application/json Content-Type: application/json { "unfurls": [ { "queueItemId": "here-goes-item-id", "content": { "className": "ApplicationUnfurlContent.Image", "title": "Title goes here", "url": "https://externalservice.url/image.png" } } ] }

プレビューでユーザーのアクションに応答する

アプリケーションがメッセージコンストラクター DSL を使用している場合、展開されたコンテンツに UI 要素 (現在はボタンのみ) を追加できます。ユーザーがこれらの要素を操作すると (ボタンをクリックするなど)、Space はアプリケーションにリクエストを送信します。リクエストには、UnfurlActionPayload タイプのペイロードが含まれています。ペイロードの内容は MessageActionPayload とほぼ同じです。唯一の違いはアクションソースです。元のメッセージの代わりに、UnfurlActionPayload は発信元を指す 2 つのプロパティを提供します。

  • link: string は、トリガーされたアクションを提供した展開されたリンクの URL です。

  • context: ApplicationUnfurlContext は、チャットメッセージ、ブログ記事、ドキュメント、コードレビュータイトル、git コミットメッセージ、課題の説明など、リンクが投稿された Space 内の正確な場所に関する情報を提供します。これは展開キュー項目と同じコンテキストです。

関連ページ:

(Kotlin) リンクを展開する方法

リンクプレビューまたはリンク展開は、ユーザーが実際にリンクをたどらなくても、リンクの背後にあるコンテンツを確認できる優れた機能です。プレビューは Space UI に直接表示され、外部リソースから取得したコンテンツが含まれています。Space では、チャットメッセージ、ドキュメント、課題の説明、コミットおよびコードレビューのタイトルなど、さまざまなコンテキストでリンクプレビューを表示できます。プレビューを構築するために、Space はページのソーシャルメタタグからの情報を使用します。要件の詳細に...

Space SDK

Space SDK は、JetBrains Space HTTP API を操作できるようにし、Space アプリケーションの開発を簡素化するライブラリです。クイックスタート:1. プロジェクト内の Space SDK を参照する次の依存関係をプロジェクトの / ファイルに追加します。// the example is given for build.gradle.kts repositories { // here go other project repos ... maven(...

同期 API

サンプル Sync API を使用したサンプルアプリケーション、Sync API は、アプリケーションが Space 内の特定のエンティティのすべての変更を確実に追跡できるようにする一連のメソッドです。変更を追跡するために、Sync API は etag (エンティティバージョン) を使用します。このアプローチにより、同期の課題 (バグやネットワークエラーなどによる) が防止され、アプリケーションによって取得されるデータが常に最新であり、Space の最新の変更との一貫性が保証されます。Space...