Space からペイロードを受信する

一部の種類のアプリケーションでは、Space はクライアントとして機能し、内部に JSON ペイロードを含む POST リクエストをアプリケーションエンドポイントに送信します。例: ユーザーがアプリケーションチャットチャネルに入力すると、Space はユーザー入力を含むペイロードを送信します。アプリケーションが Webhook 通知をサブスクライブしている場合、Space はイベントの詳細などを含むペイロードを送信します。

ペイロードの内容

ペイロードは、ペイロードクラスの名前、クラス固有のペイロードデータ、およびすべてのペイロードタイプに共通のデータ (Space URL、ユーザー ID など) で構成されます。

例: これは、ユーザーが help コマンドをチャットボットに送信するときの Space からのサンプルペイロードです。

{
    // [[[Payload class|#payload-classes]]]
    "className": "MessagePayload",
    // Class-specific payload data
    "message": {
        "messageId": "CsT000CsT",
        "channelId": "3FhQeS2URbeY",
        "messageData": null,
        "body": {
            "className": "ChatMessage.Text",
            "text": "help "
        },
        "attachments": null,
        "externalId": null,
        "createdTime": "2021-05-21T17:01:33.767Z"
    },
    // [[[Common payload data|#common-payload-data]]]
    "accessToken": "",
    "verificationToken": "abc1234",
    "userId": "1mEGCd1FvoAh",
    "serverUrl": "https://mycompany.jetbrains.space",
    "clientId": "2ulA3W2Vltg6",
    "orgId": "8fd4d79a-d164-4a71-839a-ff8f8bcd6beb"
}

ペイロードの種類

さまざまな種類のペイロードの処理を支援するために、Space SDK には多数のクラスが用意されています。これらすべてのクラスは ApplicationPayload インターフェースを実装します。

クラス	説明	関連
`AppPublicationCheckPayload`	JetBrains マーケットプレイスは、アプリケーションの検証中にこのペイロードを送信します。	JetBrains マーケットプレイスを通じて配布される複数組織アプリケーション。
`ApplicationUninstalledPayload`	Space インスタンスは、アプリケーションがこのインスタンスからアンインストールされるときに、このペイロードを送信します。	リンクまたは JetBrains マーケットプレイスを通じて配布される複数組織アプリケーション。
`InitPayload`	JetBrains Marketplace からインストールされたアプリケーションを初期化します。	リンクまたは JetBrains マーケットプレイスを通じて配布される複数組織アプリケーション。
`ListCommandsPayload`	使用可能なコマンドのリストを要求します。ユーザーがアプリケーションチャットチャネルでスラッシュ `/` または別の文字を入力すると、Space はこのペイロードタイプを送信します。アプリケーションはコマンドの JSON リストで応答する必要があります。	チャットボット、スラッシュコマンド。
`MenuActionPayload`	ユーザーが選択したカスタムメニュー項目に関する情報が含まれます。	カスタム項目を使用して Space コンテキストメニューを拡張するアプリケーション。
`MessagePayload`	ユーザーがチャットチャネルからアプリケーションに送信したメッセージが含まれます。	チャットボット、スラッシュコマンド。
`MessageActionPayload`	アプリケーションチャットチャネルでユーザーによって実行されたアクションに関する情報が含まれます。通常、これは、ボタンのクリックなど、チャットメッセージ内の UI コントロールとのユーザー操作の結果です。	チャットボット、スラッシュコマンド。
`WebhookRequestPayload`	Space で発生したイベントに関する情報が含まれています。アプリケーションは、対応する Webhook を使用してこのイベントにサブスクライブする必要があります。	Webhook を使用して Space イベントに関する通知を受信するアプリケーション。

ペイロードの読み取り

ペイロードの処理を支援するために、Space SDK は Space ヘルパーオブジェクトを提供します。これは、タイプに応じてペイロードを処理するために使用できる方法です。例: Ktor(英語) アプリケーションの場合:

@file:OptIn(ExperimentalSpaceSdkApi::class)

package com.example

import io.ktor.application.*
import io.ktor.http.*
import io.ktor.request.*
import io.ktor.response.*
import io.ktor.routing.*
import space.jetbrains.api.ExperimentalSpaceSdkApi
import space.jetbrains.api.runtime.Space
import space.jetbrains.api.runtime.helpers.RequestAdapter
import space.jetbrains.api.runtime.helpers.SpaceHttpResponse
import space.jetbrains.api.runtime.helpers.processPayload
import space.jetbrains.api.runtime.ktorClientForSpace
import space.jetbrains.api.runtime.types.InitPayload
import space.jetbrains.api.runtime.types.MenuActionPayload
import space.jetbrains.api.runtime.types.RefreshTokenPayload
import space.jetbrains.api.runtime.SpaceAppInstance
import space.jetbrains.api.runtime.helpers.SpaceAppInstanceStorage

// we use in-memory storage for storing Space instances
// in real life, use a persistent storage, e.g., a database
val spaceInstances = HashMap<String, SpaceAppInstance>()

object AppInstanceStorage : SpaceAppInstanceStorage {
    override suspend fun loadAppInstance(clientId: String): SpaceAppInstance? {
        return spaceInstances[clientId]
    }

    override suspend fun saveAppInstance(appInstance: SpaceAppInstance) {
        spaceInstances[appInstance.clientId] = appInstance
    }
}

val ktorClient = ktorClientForSpace()

class KtorRequestAdapter(private val call: ApplicationCall) : RequestAdapter {
    override suspend fun receiveText() = call.receiveText()

    override fun getHeader(headerName: String) = call.request.headers[headerName]

    override suspend fun respond(httpStatusCode: Int, body: String) {
        call.respond(HttpStatusCode.fromValue(httpStatusCode), body)
    }
}

fun Routing.routes() {
    post("api/myapp") {
        Space.processPayload(KtorRequestAdapter(call), ktorClient, AppInstanceStorage) { payload ->
            // analyze payload type
            when (payload) {
                is InitPayload -> {
                    // initialize the app...

                    SpaceHttpResponse.RespondWithOk
                }
                is MenuActionPayload -> {
                    // react to menu item click
                    // val result = ...
                    SpaceHttpResponse.RespondWithResult(result)
                }
                is RefreshTokenPayload -> {
                    // save refresh token...

                    SpaceHttpResponse.RespondWithOk
                }
                else -> {
                    SpaceHttpResponse.RespondWithOk
                }
            }
        }
    }
}

より一般的なアプローチでは、ペイロードの処理に readPayload(body: String): ApplicationPayload SDK ヘルパー関数のみを使用できます。

fun main() {
    embeddedServer(Netty, port = 8080) {
        routing {
            post("/api/from-space") {
                val body = call.receiveText()
                val payload = readPayload(body)

                // analyze payload type
                when (payload) {
                    is MessagePayload -> {
                        println("This is MessagePayload")
                        call.respond(HttpStatusCode.OK, "")
                    }
                    else -> call.respond(HttpStatusCode.BadRequest,
                        "Unsupported payload type")
                }
            }
        }
    }.start(wait = true)
}

共通ペイロードデータ

タイプに関係なく、Space から送信されるペイロードには常に、ユーザー ID、サーバー URL などの共通情報が含まれています。このデータの取得を支援するために、Space SDK は ApplicationPayload インターフェース用の拡張メソッドを多数提供しています。

val payload = readPayload(body)

// ID of a user who initiated the request
// Not available for the payload types that
// do not imply user interaction
val userId = payload.userId

// Client ID issued to the app
// during the [[[app registration|https://www.jetbrains.com/help/space/register-app-in-space.html]]]
val clientId = payload.clientId

// URL of your Space instance
val url = payload.serverUrl

// ID of your organization in Space
val orgId = payload.orgId

// Verification token
// used to [[[verify Space in the app|https://www.jetbrains.com/help/space/verify-requests-from-space.html]]]
// null if you choose other verification way
val token = payload.verificationToken

最終更新日: 2023 年 5 月 25 日

関連ページ：

複数組織アプリケーションの配布

マルチ組織アプリケーションは、複数の Space 組織にインストールできるアプリケーションです。組織ユーザーは、直接リンクをクリックするか、JetBrains マーケットプレイスを使用してアプリケーションをインストールできます。アプリケーションを複数の組織で使用できるようにするには、Space API 呼び出しを介して特定の組織内でアプリケーション自体を構成できる必要があります。アプリケーション構成の詳細については、こちらを参照します。複数組織アプリケーションの詳細：クライアントクレデンシャル...

チャットメッセージ

チュートリアル (Kotlin) チャットボットの作成方法、(.NET) チャットボットの作成方法、(Kotlin) インタラクティブ UI をメッセージに追加する方法、サンプル Kotlin で書かれたシンプルなチャットボット、C# で書かれたシンプルなチャットボット、アプリケーション (チャットボットなど) は、アプリケーションチャットチャネルを通じて Space ユーザーと対話できます。アプリケーションチャットチャネルでは、Space ユーザーは次のことができます。アプリケーションコマンドのリ...

カスタムメニュー項目

サンプルカスタムメニュー項目を課題コンテキストメニューに追加するサンプルアプリケーション、アプリケーションは、Space のコンテキストメニューにカスタムメニュー項目を追加できます。ユーザーがカスタム項目をクリックすると、Space はアプリケーションにメッセージを送信します。メッセージには、タイプのペイロードが含まれています。カスタムメニュー項目を追加できる場所：現在、次の Space エンティティのコンテキストメニューはカスタム項目で拡張できます。課題、チャットメッセージ、コードレビュー、...

Web フック

サンプル Space Webhook を使用するサンプルアプリケーション、Webhook を使用すると、アプリケーションは Space のイベントに関する通知を受信できるようになります。イベントがトリガーされると、Space は指定されたアプリケーションエンドポイントに POST リクエストを送信します。リクエストには、イベントの詳細を含む JSON ペイロードが含まれています。Space では、Webhook はアプリケーションの不可欠な部分です。各アプリケーションは、独自の構成済み Webho...

Space からのリクエストを検証する

アプリケーションが Space からリクエストを受信することになっている場合 (たとえば、エンドポイントでリクエストをリッスンするチャットボット)、受信したリクエストが本物かどうかを検証できる必要があります。Space では、さまざまな検証方法が提供されます。(推奨) 公開鍵、署名キー、(廃止された) 検証トークン、SSL クライアント証明書、HTTP 認証、(推奨) 公開鍵：この検証方法は非対称暗号化に基づいています。最も安全なものとして使用することをお勧めします。Space SDK は、こ...