Space SDK

Space SDK は、JetBrains Space HTTP API を操作できるようにし、Space アプリケーションの開発を簡素化するライブラリです。

クイックスタート

1. プロジェクト内の Space SDK を参照する

次の依存関係をプロジェクトの build.gradle/build.gradle.kts ファイルに追加します。

// the example is given for build.gradle.kts
repositories {
    // here go other project repos ...
    maven("https://maven.pkg.jetbrains.space/public/p/space/maven")
}
dependencies {
    // here go other dependencies ...

    // We use SDK v.159302, but when you read this guide, a newer version may be available.
    // To find out which SDK version is the latest available: open API Playground,
    // in the "Code" section on the right, choose "Kotlin SDK", and click "Set up dependency..."
    implementation("org.jetbrains:space-sdk-jvm:159302-beta")
    // We also need a Ktor client
    implementation("io.ktor:ktor-client-cio-jvm:2.0.3")
}

2. Space アクセストークンの作成

呼び出しを行うには、アプリケーションはまず Space で認証する必要があります。通常、アプリケーションを Space に登録し、受信したクライアント ID とシークレットを認証に使用する必要があります (クライアント資格情報 OAuth 2.0 フロー)。ただし、テスト目的の場合は、個人トークンを作成する方が速くて簡単です。

個人トークンを作成します。
トークンを作成するときに、アプリケーションに必要な権限を指定します (たとえば、Space ユーザーにメッセージを送信するには、グローバルコンテキストでダイレクトメッセージを送信するを付与します)。運用アプリケーションは、その認証フローに応じて、他の方法を使用して必要な権限を取得する必要があることに注意してください。

3. Space クライアントの作成

Space SDK は、Space への呼び出しを簡素化するクライアントを提供します。

import space.jetbrains.api.runtime.SpaceAuth
import space.jetbrains.api.runtime.SpaceClient
import space.jetbrains.api.runtime.ktorClientForSpace

val spaceHttpClient = ktorClientForSpace()
// serverUrl - URL of your Space instance
// token - access token created in the previous step
val spaceClient = SpaceClient(ktorClient = spaceHttpClient,
    serverUrl = "https://mycompany.jetbrains.space",
    token = "here-goes-access-token")

4. Space を呼び出す

Space クライアントを使用して、Space インスタンスを呼び出します。

spaceClient.chats.messages.sendMessage(
    channel = ChannelIdentifier.Profile(ProfileIdentifier.Username("John.Doe")),
    content = message {
        section { text("Hello from my app!") }
    }
)

Space エンドポイントの操作方法を学ぶ

1. プロジェクト内の Space SDK を参照する

Space SDK クライアントをプロジェクトに追加します。例: dotnet コマンドラインツールを使用した場合:

dotnet add package JetBrains.Space.Client --version 1.0.0-beta.v2022.2.0-DEV.113510.9115

SDK 1.0.0-beta.v2022.2.0-DEV.113510.9115 を使用していますが、このガイドを読むと、より新しいバージョンが利用可能になる可能性があります。

2. Space アクセストークンの作成

個人トークンを作成します。
トークンを作成するときに、アプリケーションに必要な権限を指定します (たとえば、Space ユーザーにメッセージを送信するには、グローバルコンテキストでダイレクトメッセージを送信するを付与します)。運用アプリケーションは、その認証フローに応じて、他の方法を使用して必要な権限を取得する必要があることに注意してください。

3. Space 接続の作成

using JetBrains.Space.Client;
using JetBrains.Space.Common;

// url of your Space instance
var url = new Uri("https://mycompany.jetbrains.space");
// access token created in the previous step
var token = "here-goes-access-token";
var authTokens = new AuthenticationTokens(token);
var connection = new BearerTokenConnection(url, authTokens);

4. Space を呼び出す

必要なクライアントを作成し、Space インスタンスを呼び出します。

// create a client that will send chat messages
var chatClient = new ChatClient(connection);

await chatClient.Messages.SendMessageAsync(
    recipient: MessageRecipient.Member(ProfileIdentifier.Username("John.Doe")),
    content: new ChatMessageText("Hello from my app!"));

Space エンドポイントの操作方法を学ぶ

Space SDK の内容

Space SDK は以下を提供します。

Space HTTP API クライアント – クライアントは Space エンドポイントへのアクセスを提供
Space からのリクエストの処理 – Space リクエストで受信したペイロードの処理に役立つクラスのセット。
チャットメッセージのフォーマット、Space ペイロードの処理など、定型コードを削減できるさまざまなヘルパーユーティリティ。

Space SDK ディストリビューション

SDK には 2 つのバージョンがあります。

Kotlin 用の Space SDK は、パブリック JetBrains Space リポジトリ(英語)で入手できます。
- org.jetbrains:space-sdk-jvm:{version} – Java 仮想マシン (JVM) 上で使用できる Space HTTP API クライアント。
- org.jetbrains:space-sdk-js:{version} – Kotlin/JS で使用できる Space HTTP API クライアント。
Space SDK for .NET は nuget.org(英語) で入手できます。
- JetBrains.Space.Client — Space HTTP API で動作するように生成されたクライアントコード。
- JetBrains.Space.AspNetCore — ASP.NET Core で JetBrains.Space を使用するためのヘルパー。
- JetBrains.Space.AspNetCore.Authentication — ASP.NET Core と統合される認証プロバイダー。

Space HTTP API クライアント: Space エンドポイントの操作

Space SDK の重要な部分は、Space HTTP API クライアントです。とりわけ、クライアントは Space エンドポイントへの直接アクセスを提供します。SpaceHttpClient の対応するプロパティとメソッドは、API Playground と同じように構造化されています。playground は、いつでも対話型ヘルプとして使用でき、クライアントコードジェネレーターとしても使用できます。

Space からデータを取得する

Space エンドポイントを使用して、Space からデータを取得できます。例: これは、チームディレクトリからユーザープロファイルを取得する方法です。

val appInstance = AppInstance(clientId, clientSecret, spaceServerUrl)
// requires the ViewProfile permission
SpaceClient(appInstance, SpaceAuth.ClientCredentials()).use {
    it.teamDirectory.profiles.getProfile(ProfileIdentifier.Username("John.Doe"))
}

memberProfile には id、username、about などのプロファイルのプロパティがあります。

Space モジュールの操作

Space エンドポイントを使用すると、Space で多くの操作を実行できます。チャットメッセージの送信、ブログ投稿の作成、プロジェクトメンバーの追加、コードレビューの終了などを行います。例: これはブログ投稿を公開する方法です:

val client = SpaceHttpClient(HttpClient())
    .withServiceAccountTokenSource(id, secret, url)

// requires the PublishArticles right
client.blog.publishBlogPost(
    title = "My First Blog Post",
    content = "Hello World!"
)

アプリケーションの権限

Space エンドポイントに対して get または set リクエストを実行するには、アプリケーションに対応するアクセス許可が必要です。権限をリクエストする方法を学びます。

API Playground で特定の呼び出しを実行するために必要な権限を確認できます。

フィールドとプロパティ

すべての Space 応答には、要求されたデータを含む JSON オブジェクトが含まれています。デフォルトでは、取得するフィールドを指定しない場合、この JSON オブジェクトにはすべてのトップレベルのプロパティが含まれます。

HTTP リクエスト: GET https://jetbrains.team/api/http/team-directory/profiles/username:John.Doe Authorization: Bearer abc123 Accept: application/json
レスポンス: { "id": "2asfen24Jx6u", "username": "John.Doe", "name": { "firstName": "John", "lastName": "Doe" }, "speaksEnglish": true, "smallAvatar": "vYK0b1Qisdf2C", "avatar": "40uDKb4RHdsst", ...

Space SDK を使用して同じリクエストを実行できます。

val memberProfile = spaceClient.teamDirectory.profiles
    .getProfile(ProfileIdentifier.Username("John.Doe"))

部分的な回答

ほとんどのリクエストでは、Space から取得したい結果を形にすることができます。例: ユーザー id と about の説明のみを取得するには、API リクエストの $fields パラメーターを $fields=id,about に設定します。

アプリケーションが必要とする情報だけを取得できるため、ペイロードサイズの削減に役立ち、全体的なパフォーマンスが向上します。

HTTP リクエスト: GET https://jetbrains.team/api/http/team-directory/profiles/username:John.Doe?$fields=id,about Authorization: Bearer abc123 Accept: application/json
レスポンス: { "id": "2asfen24Jx6u", "about": "Johny is a nice man" }

Space SDK を使用してこのようなリクエストを実行するには、いわゆる部分メソッド (この場合は id() と about()) を使用する必要があります。

val memberProfile = spaceClient.teamDirectory.profiles
    .getProfile(ProfileIdentifier.Username("John.Doe")
    ) {
        id()
        about()
    }

応答に含まれていない memberProfile.name プロパティにアクセスしようとすると、Space HTTP クライアントは追加情報を含む IllegalStateException をスローします。

try {
    // This will fail...
    println("${memberProfile.name.firstName} ${memberProfile.name.lastName}")
} catch (e: IllegalStateException) {
    // ...and you'll get a pointer about why it fails:
    // Property 'name' was not requested. Reference chain: getAllProfiles->data->[0]->name
    println("The Space API client tells us which partial query should be added to access the property:");
    println(e.message)
}

フィールドは値型 (整数、文字列、ブール値など) だけでなく、複合型の場合もあることに注意してください。たとえば、ユーザープロファイルには TD_ProfileName の name フィールドがあり、TD_ProfileName には firstName フィールドと lastName フィールドがあります。この階層を要求するには、$fields=name(firstName,lastName) をクエリする必要があります。

ネストされたプロパティ

このようなリクエストを実行すると、次のようになります。

val memberProfile = spaceClient.teamDirectory.profiles
    .getProfile(ProfileIdentifier.Username("John.Doe"))

Space は、多くのトップレベルプロパティ ( id、username、about など) を含む TD_MemberProfile 型のインスタンスを返します。その中には、ネストされた TD_MemberProfile インスタンスのコレクションである managers プロパティがあります。このようなプロパティはデフォルトでは取得されません。これは明示的に行う必要があります。

例: マネージャー名を含むユーザープロファイルの managers を取得する場合は、デフォルトの部分結果を拡張してこれらのプロパティを要求する必要があります。

val memberProfile = spaceClient.teamDirectory.profiles
    .getProfile(ProfileIdentifier.Username("John.Doe")) {
        defaultPartial()        // with all top level fields
        managers {              // include managers
            id()                //   with their id
            username()          //   and their username
            name {              //   and their name
                firstName()     //     with firstName
                lastName()      //     and firstName
            }
        }
    }

ここに:

defaultPartial() : 現在のレベル (* フィールド定義) にすべてのフィールドを追加する特別な部分メソッド。

再帰的な応答

memberProfile.managers の例は、すべてのマネージャーが独自のマネージャーを持つことができるため、非常に興味深いものです (誰がマネージャーを持つこともでき、誰が ...)。このツリーにマネージャーが何人いるかわからないため、再帰応答を要求できます。マネージャーツリー全体が返されます。

このようなツリー構造を表す関数には、再帰応答を取得するための特別なオーバーロードがあります。たとえば、managers の場合は managers(recursiveAs: TD_MemberProfilePartial) です。使用方法は次のとおりです。

val memberProfile = spaceClient.teamDirectory.profiles
    .getProfile(ProfileIdentifier.Username("John.Doe")) {
        defaultPartial()  // with all top level fields
        managers(this)    // and the same fields for all managers
    }

継承

サブクラス (多態性応答) を返す Space エンドポイントがいくつかあります。

そのような例の 1 つは spaceClient.projects.planning.issues.getAllIssues() です。ここで、createdBy プロパティは CPrincipalDetails のサブクラスにすることができます。

CAutomationTaskPrincipalDetails (課題が自動化タスクによって作成された場合)。
CBuiltInServicePrincipalDetails、課題が Space 自体によって作成された場合。
CExternalServicePrincipalDetails (課題が外部サービスによって作成された場合)。
CUserWithEmailPrincipalDetails (課題がメールアドレスを持つユーザーによって作成された場合)。
CUserPrincipalDetails (課題がユーザーによって作成された場合)。

部分ビルダーには、これらすべてのクラスのプロパティが含まれています。

プロジェクトから課題を取得する例を次に示します。createdBy プロパティについては、応答に次の内容が含まれるように定義しています。

CUserPrincipalDetails と user.id プロパティ。
CUserWithEmailPrincipalDetails と name および email プロパティ。

val issueStatuses = spaceClient.projects.planning.issues.statuses
    .getAllIssueStatuses(ProjectIdentifier.Key("CRL")).map { it.id }

val issues = spaceClient.projects.planning.issues
    .getAllIssues(ProjectIdentifier.Key("CRL"),
        sorting = IssuesSorting.UPDATED,
        descending = true,
        statuses = issueStatuses) {
        defaultPartial()
        creationTime()
        createdBy {
            details {
                // Available on CUserPrincipalDetails
                user {
                    id()
                }

                // Available on CUserWithEmailPrincipalDetails,
                // CAutomationTaskPrincipalDetails, CBuiltInServicePrincipalDetails
                name()
                email()
            }
        }
        status()
    }.data.forEach { issue ->
        when (issue.createdBy.details) {
            is CUserPrincipalDetails -> {
                // ...
            }
            is CUserWithEmailPrincipalDetails -> {
                // ...
            }
        }
    }

これらの型をキャストしたり、それらに対して when 式を使用したりすることができます。

バッチ

結果のコレクションを返すことができるリクエストは多数あります。パフォーマンスを向上させるために、これらの応答はページ分割され、バッチで取得できます。

必要なデータ型のプロパティを指定する必要があります。例: id と content を含む、ある日付のユーザーの ToDo 項目を取得してみましょう。

// Get all To-Do
var todoBatchInfo = BatchInfo("0", 100)
do {
    val todoBatch = spaceClient.todoItems
        .getAllTodoItems(from = LocalDate(2020, 01, 01), batchInfo = todoBatchInfo) {
            id()
            content()
        }

    todoBatch.data.forEach { todo ->
        // ...
    }

    todoBatchInfo = BatchInfo(todoBatch.next, 100)
} while (todoBatch.hasNext())

ここに:

hasNext() : さらに結果を取得する必要があるかどうかを判断できる拡張メソッド:
fun Batch<*>.hasNext() = !data.isEmpty()

結果のバッチには 1 ページの結果が含まれます。さらに多くの To-Do 項目を取得するには、追加の API 呼び出しを行う必要があります。

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

JetBrains Space ヘルプ

Space SDK

クイックスタート

1. プロジェクト内の Space SDK を参照する

2. Space アクセストークンの作成

3. Space クライアントの作成

4. Space を呼び出す

1. プロジェクト内の Space SDK を参照する

2. Space アクセストークンの作成

3. Space 接続の作成

4. Space を呼び出す

Space SDK の内容

Space SDK ディストリビューション

Space HTTP API クライアント: Space エンドポイントの操作

Space からデータを取得する

Space モジュールの操作

アプリケーションの権限

フィールドとプロパティ

部分的な回答

ネストされたプロパティ

再帰的な応答

継承

バッチ

関連ページ：