JetBrains Space ヘルプ

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

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

複数組織アプリケーションの詳細

  • クライアントクレデンシャルフローによる認証はデフォルトで有効になっています。

  • 公開鍵による検証は常に有効です。

  • ユーザーが複数組織アプリケーションをインストールすると、Space は初期化ペイロード InitPayload をアプリケーションエンドポイントに送信します。

  • ユーザーが複数組織アプリケーションをアンインストールすると、Space はアンインストールペイロード ApplicationUninstalledPayload をアプリケーションエンドポイントに送信します。

  • アプリケーション自体のみがパラメーター (認可フロー、認証、Webhook など) を変更できます。Space ユーザー (管理者を含む) は、パラメーターを変更したり、アプリケーションに送信されたペイロードを表示したりすることはできません。これは、Space ユーザーがアプリケーションデータに不正にアクセスしたり、アプリケーションになりすましたりするのを防ぐために行われます。

ディストリビューション用のアプリケーションを準備する

単一組織アプリケーションには手動構成が必要です。Space のアプリケーションページで、ユーザーは必要な拡張機能、アプリケーション権限、Webhook、その他の設定を指定する必要があります。逆に、複数組織のアプリケーションは、そのような構成を単独で実行できなければなりません。主な設定手順を以下に説明します。

1. InitPayload の処理

アプリケーションのインストール中に、ユーザーがインストールボタンをクリックすると、Space は InitPayload タイプのペイロードをアプリケーションエンドポイントに送信します。ペイロードは次のようになります。

{ "className": "InitPayload", // Client secret issued to the app "clientSecret": "2e14111c13daa385590ded764c0ec8d3fd20ae02ce96d0c7e1728e7", // URL of Space instance where the app is installed "serverUrl": "https://mycompany.jetbrains.space", // A string value that Space sends back to the application // Can be used to track installation state "state": "", // Client ID issued to the app "clientId": "81ec3fba-95ca-4995-9b44-218e743", // ID of the user who installed the app to the orgranization "userId": "2BgVYn24Jx6u" }

アプリケーション開発者としてのあなたのタスクは、アプリケーション内で InitPayload を処理することです。ペイロードを受信すると、アプリケーションは基本パラメーターを構成する必要があります。つまり、必要な拡張機能、権限、その他の設定を指定します。

Kotlin Space SDK では、Space ヘルパーオブジェクトを使用してペイロードを処理できます。例: Ktor アプリケーションの場合:

// we use in-memory storage for storing Space instances // in a real app, 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 } override suspend fun removeAppInstance(clientId: String) { spaceInstances.remove(appInstance.clientId) } } 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 -> when (payload) { is InitPayload -> { // Handle the payload: // 1. Specify required UI extensions // 2. Request permissions // 3. Other activities // If initialization is successful, // respond with HTTP 200 OK SpaceHttpResponse.RespondWithOk } else -> { SpaceHttpResponse.RespondWithOk } } } } }

2. 必要な UI 拡張機能を指定する

アプリケーションは、Space に特定の拡張機能を有効にするよう明示的に要求する必要があります。例: アプリケーションがチャットボットの場合、チャットボット機能が必要です。たとえば、課題メニュー項目にメニュー項目を追加する場合は、発行メニュー項目機能などが必要になります。

機能を有効にするには、アプリケーションは Space API を使用する必要があります。例:

space.applications.setUiExtensions( contextIdentifier = ProjectPermissionContextIdentifier(ProjectIdentifier.Id("2WnWIP2gPOyz")), extensions = listOf(IssueMenuItemUiExtensionIn( displayName = "Custom item", description = null, menuItemUniqueCode = "abc1234", visibilityFilters = emptyList() )) )
PATCH https://jetbrains.team/api/http/applications/ui-extensions Authorization: Bearer here-goes-auth-token Accept: application/json Content-Type: application/json { "contextIdentifier": "project:id:2WnWIP2gPOyz", "extensions": [ { "className": "IssueMenuItemUiExtensionIn", "displayName": "Custom item", "menuItemUniqueCode": "abc1234", "visibilityFilters": [] } ] }

3. 権限をリクエストする

特定の Space エンドポイントを呼び出す前に、アプリケーションは対応するアクセス許可を取得する必要があります。このプロセスの正確な実装は、選択した承認フローによって異なります。詳細

4. その他の活動

初期化フェーズには、Webhook の登録、Space からのデータの取得、必要な Space エンティティの作成などの追加アクティビティが含まれる場合があります。Space API を呼び出すことでアプリケーション設定を更新できることに注意してください。例: アプリケーション名を変更するには:

space.applications.updateApplication( application = ApplicationIdentifier.ClientId("here-goes-app-client-id"), name = "new-app-name" )
PATCH https://jetbrains.team/api/http/applications/clientId:here-goes-app-client-id Authorization: Bearer here-goes-auth-token Accept: application/json Content-Type: application/json { "name": "new-app-name" }

5. AppPublicationCheckPayload の処理 (JetBrains マーケットプレイスアプリのみ)

アプリケーションを JetBrains Marketplace に送信すると、検証プロセスが実行されます。これには、基本的なヘルスチェックに合格することが含まれます。JetBrains マーケットプレイスは、アプリケーションのエンドポイントに AppPublicationCheckPayload を送信します。アプリケーションは 200 OK HTTP ステータスコードで応答する必要があります。

ここに示すようにアプリケーションで Space.processPayload() ヘルパーメソッドを使用する場合は、自分で処理を実装する必要はありません。AppPublicationCheckPayload は自動的に処理されます。それ以外の場合はすべて、ペイロードを処理するコードを追加する必要があります。例:

//... post("api/space") { val body = call.receiveText() // ... when (val payload = readPayload(body)) { // ... is AppPublicationCheckPayload -> { call.respond(HttpStatusCode.OK) } } }

6. アプリケーションのアンインストールペイロードの処理

ユーザーがアプリケーションをアンインストールすると、Space は ApplicationUninstalledPayload を送信してアプリケーションに通知します。アプリケーションがペイロードを処理している間も、リクエストを Space に送信できます。

ペイロードを受信すると、アプリケーションは 200 OK HTTP ステータスコードで応答する必要があります。ここに示すようにアプリケーションで Space.processPayload() ヘルパーメソッドを使用する場合は、自分で処理を実装する必要はありません。ApplicationUninstalledPayload は、SpaceAppInstanceStorage.removeAppInstance メソッドの呼び出しを含めて自動的に処理されます (ただし、ここでもストレージからアプリケーションインスタンスを削除する実装が必要です)。それ以外の場合はすべて、ペイロードを処理するコードを追加する必要があります。例:

//... post("api/space") { val body = call.receiveText() // ... when (val payload = readPayload(body)) { // ... is ApplicationUninstalledPayload -> { // Add uninstall activities, e.g., // remove Space instance data from the database // ... call.respond(HttpStatusCode.OK) } } }

アプリケーションが 200 OK で応答しない場合、Space はさらに数回 ApplicationUninstalledPayload の配信を試行します。すべての試行が失敗した場合でも、Space はアプリケーションを削除します。試行中に、ユーザーはアプリケーションを強制的にアンインストールできます。

JetBrains マーケットプレイス経由でアプリケーションを配布する

JetBrains マーケットプレイス経由でアプリケーションをディストリビューションする主な利点は、この場合、Space を使用するすべての企業が拡張 | アプリケーションページからアプリケーションを見つけてインストールできることです。一般的なディストリビューションフローは次のようになります。

  1. アプリケーションを JetBrains マーケットプレイスに追加します。

  2. Space ユーザーは、拡張 | アプリケーションページを通じて、または JetBrains Marketplace によって生成されたインストールリンクをクリックして、アプリケーションをインストールします。

    Install from Marketplace

  3. ユーザーはアプリケーションのインストールダイアログにリダイレクトされます。

  4. ユーザーがダイアログ内で「インストール」をクリックします。

  5. この時点で、Space は InitPayload をアプリケーションエンドポイントに送信します。

  6. アプリケーションは初期化を実行し、200 OK HTTP ステータスコードで応答します。

  7. アプリケーションは、Space 組織の拡張 | 組織にインストールページに表示されます。

アプリケーションを JetBrains マーケットプレイスに追加するには

  1. https://plugins.jetbrains.com/(英語) に登録する

  2. 右上隅にあるプロファイルをクリックし、プラグインのアップロードを選択します。これにより、アップロードページが開きます。

  3. 左側の製品リストで、IDE を Space に変更します。

  4. アプリケーション設定を指定します。

    • Name、ID、説明は、アプリケーション名、一意の識別子、アプリケーションの短い説明を表します。

    • エンドポイントは、アプリケーションエンドポイントの HTTPS URL です。Space はそれを使用してアプリケーションにメッセージを送信します。

    • Icon、ベンダー、ライセンスは、アプリケーションアイコン (SVG 形式)、開発会社、アプリケーションの配布に使用されるライセンスを表します。

    • 最小 Space バージョンは、サポートされる Space オンプレミスの最小バージョンです。HTTP API は常に更新されるため、アプリケーションは必要なバージョンを明示的に宣言する必要があります。

    • メール。アプリケーションが Space リポジトリにコミットをプッシュする場合、committer フィールドでこのメールを使用できます。これは、リポジトリに対してコミッターの検証オプションが有効になっている場合に必要です。

    • アプリケーションで有効にする場合は、認証フローで認証コードフローを選択します。有効にする場合は、フローオプション (リダイレクト URI と PKCE 要件) を指定します。詳細

      クライアントクレデンシャルフローは、デフォルトで複数組織アプリケーションに対して有効になっています。これを無効にするのは、アプリケーションが認証コードフローを使用して Space で認証する静的 Web ページである場合にのみ意味があります。詳細

  5. アプリケーションの追加をクリックします。

  6. ここで、アプリケーションは JetBrains によって検証される必要があります。検証には基本的なヘルスチェックが含まれることに注意してください。確認のために送信するボタンをクリックすると、チェックを開始できます。それ以外の場合、マーケットプレイス管理者によって開始されます。検証プロセスの詳細については、こちら(英語)を参照してください。

  7. アプリケーションが検証されると、すべての Space 組織の管理 | アプリケーション | マーケットプレースページに表示されます。

JetBrains マーケットプレイスの代わりに、直接リンクを使用してアプリケーションを配布できます。必要なのは、リンクを生成して Space ユーザーに提供することだけです。

一般的なディストリビューションフローは次のようになります。

  1. アプリケーションのディストリビューションリンクを作成します。

  2. Space ユーザーはブラウザーでリンクをクリックし、Space 組織を選択します。

  3. ユーザーは、Space 組織のアプリケーション接続ダイアログにリダイレクトされます。

    App connect dialog

  4. ユーザーがダイアログ内で「接続」をクリックします。

  5. この時点で、Space は InitPayload をアプリケーションエンドポイントに送信します。

  6. アプリケーションは初期化を実行し、200 OK HTTP ステータスコードで応答する必要があります。

  7. この後、アプリケーションは Space 組織の拡張 | 組織にインストールページに表示されます。

Space アプリケーションは 3 つのリンクタイプをサポートします。

  1. JetBrains マーケットプレイスで入手可能なアプリケーションへのリンク:

    https://jetbrains.com/space/app/install-app?marketplace-app=<marketplace-application-id>&name=<url-encoded-app-name>

  2. 一般的なリンク:

    https://jetbrains.com/space/app/install-app?<app-params>

  3. 特定の組織向けにパーソナライズされたリンク:

    https://somecompany.jetbrains.space/extensions/installedApplications/new?<app-params>

    上記のリンクは、somecompany 組織でのみ機能します。

URL パラメーター (<app-params>) を使用して、アプリケーション設定を構成できます。詳細は以下を参照してください。

一般設定 :

  • name : (必須) デフォルトのアプリケーション名。Space 組織のユーザーは、インストール後にこの名前を変更できます。

  • endpoint : アプリケーションエンドポイントの HTTPS URL (URL エンコード)。Space はそれを使用してアプリケーションにメッセージを送信します。

  • pair : デフォルトでは true pair=true の場合、アプリケーションが組織に追加された後、Space は初期化ペイロード InitPayload をアプリケーションに送信します。アプリケーションで InitPayload を処理しない場合は、pair=false を設定します。

  • state : Space が初期化ペイロード InitPayload でアプリケーションに送信する文字列値。これを使用して、ユーザーがブラウザーでリダイレクトされている間に、さまざまなシステム間でのインストールプロセスを追跡します。

  • min-space-version : サポートされている最小の Space オンプレミスバージョン。HTTP API は常に更新されるため、アプリケーションは必要なバージョンを宣言することをお勧めします。このパラメーターをスキップすると、アプリケーションはあらゆる Space On-Premises バージョンと互換性があるとみなされます。

  • email : アプリケーションが Space リポジトリにコミットをプッシュする場合、このメールを committer フィールドで使用できます。これは、リポジトリに対してコミッターの検証オプションが有効になっている場合に必要です。

認可設定 :

  • client-credentials-flow-enabled : デフォルトでは、true client-credentials-flow-enabled=false を設定して、アプリケーションのクライアントクレデンシャルフローを無効にします。これは、アプリケーションが認可コードフローを使用して Space で認可を行う静的 Web ページである場合にのみ意味があります。詳細

  • code-flow-enabled : code-flow-enabled=true を設定して、アプリケーションの認証コードフローを有効にします。

  • code-flow-redirect-uris : ( code-flow-enabled=true の場合は必須) 認証コードフローのリダイレクト URI。

  • pkce-required : pkce-required=true を設定して、認証コードフローの PKCE 検証を有効にします。

Space リクエストの検証 ( 公開鍵による検証が推奨されており、常に有効になっていることに注意してください):

例: 一般的なリンクは次のようになります。

https://jetbrains.com/space/app/install-app?name=Homepage%20demo&endpoint=https%3A%2F%2Fspace-app-homepage-example.eu-west-1.eks.intellij.net%2Fapi%2Fspace&code-flow-enabled=true&code-flow-redirect-uris=https%3A%2F%2Fnowhere.domain&min-space-version=2023.1

単一組織アプリケーションの登録 アプリケーションのバージョン管理

関連ページ：

クライアント資格情報フロー

基本：アプリケーション自体に代わって承認を行います。チャットボットなど、自分自身に代わってアクションを実行するサーバー側アプリケーションに適しています。クライアント資格情報フローでは、アプリケーションはおよびを送信することで Space からアクセストークンを受け取ります。アプリケーションで Space SDK を使用する場合は、メソッドを利用してフローを実装できます。クライアント資格情報フローを使用してすべての操作にアクセスできるわけではありません。多くのアクション (記事の下書きの投稿など...

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

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

権限のリクエスト

特定の Space エンドポイントにアクセスするには、アプリケーションはまず対応するアクセス許可を取得する必要があります。例: アプリケーションがプロジェクトの課題を作成する場合、アプリケーションには課題の作成権限が必要です。課題の詳細を表示するには、課題を表示する権限が必要です。アプリケーションに必要な権限のセット全体は、権限スコープと呼ばれます。アプリケーションがアクセス許可を要求する方法は、アプリケーション自体の代わりに動作するアプリケーションと、Space ユーザーの代わりに動作するアプ...

アプリケーションのインストール

Space アプリケーションは、JetBrains マーケットプレイスと直接リンクという 2 つの主なソースを通じて配布されます。JetBrains マーケットプレイスからアプリケーションをインストールする：メインメニューで、拡張をクリックし、マーケットプレースを選択します。目的のアプリケーションを見つけて、「インストール」をクリックします。アプリケーションのインストールウィンドウが表示されます。アプリケーションのインストールウィンドウで、「インストール」をクリックします。この後、Space...

プッシュ制限を設定する

特定のルールを強制し、準拠していないプッシュを禁止することで、リポジトリを保護できます。認証されていないコミッターからのコミットを禁止したり、GPG コミット署名を強制および検証したり、正規表現を使用してコミットメッセージ規約を設定したり、サイズが大きすぎるファイルや不要なファイルのプッシュを禁止したりできます。プロジェクトに移動すると入力してリポジトリを開きます。リポジトリページで、「設定」をクリックします。プッシュ制限タブに移動します。編集を押します。制限を適用し (以下の説明を参照)、完了...