JetBrains Space ヘルプ

同期 API

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

Space とサードパーティの課題トラッカーを統合するアプリケーションを開発しているとします。このようなシナリオでは、アプリケーションは Sync API を使用して、Space と同期して課題の一貫した状態を維持できます。

Sync API が役立つもう 1 つの例は、特定の Space 通知 (チャネル内のチャットメッセージなど) を追跡する必要があるアプリケーションです。このようなアプリケーションの主な作業は、チャネル内のメッセージを 1 つも見逃さないようにすることです。ここでの効果的な戦略は、Sync API を Webhook と組み合わせて使用することです。Webhook は新しいメッセージが投稿されると通知しますが、同期 API を定期的に呼び出して、メッセージが欠落していないかを再確認できます (ネットワークの中断中にメッセージが送信される可能性があるなど)。

同期 API は現在、次の Space エンティティで利用できます。

これらのエンティティに対して、Sync API を使用すると次のことが可能になります。

  • 特定のエンティティのレコードを取得する

  • レコードの更新を確実に受信して処理する

同期 API を使用する

サポートされているすべてのエンティティに対して、Sync API は Get sync batch メソッドを提供します。sync フィルターを使用すると、API Playground 内のすべての同期メソッドを見つけることができます。

Sync calls in API Playground

例: これは、Get sync batch メソッドを使用してプロジェクト内のすべての課題を取得する方法です。

var latestEtag = etag var hasMore = true while (hasMore) { // get a batch of issues using Sync API val batch = spaceClient.projects.planning.issues.getSyncBatch( project = ProjectIdentifier.Id(projectId), // we get not all issues at once but in batches of `batchSize` // starting with the issue that has the `latestEtag` batchInfo = SyncBatchInfo.SinceEtag( etag = latestEtag, batchSize = 50 ) ) // do something with batch.data // ... // `latestEtag` is now the etag of the last issue in the batch latestEtag = batch.etag hasMore = batch.hasMore }

完全な例はここで参照してください。

MY-PRJ プロジェクト内のすべての課題を返す単一のリクエスト:

GET https://mycompany.jetbrains.space/api/http/projects/key:MY-PRJ/planning/issues/sync-batch?batchInfo={etag:0,batchSize:50} Authorization: Bearer here_goes_your_token Accept: application/json

同期 API の仕組み

  • Sync API はエンティティではなくレコードを操作します。レコードは、特定の時点におけるエンティティを表します。これには、エンティティのデータとその etag (エンティティのバージョン) が含まれます。エンティティが作成、更新、削除されるたびに、etag 値が増加します。

  • 呼び出すときは、最後に受信したレコードの etag を指定します。返されるレコードには、指定された etag から始まる Space エンティティが含まれます。すべてのエンティティを取得するには、etag に 0 を指定します。

    すべての Sync API メソッドは次のデータ構造を返します。

    フィールド

    タイプ

    説明

    data

    チャットメッセージの場合: ChannelItemSyncRecord

    絵文字の場合: CustomEmojiInfo

    課題について: Issue

    チーム向け: TD_Team

    Space エンティティのバッチ。エンティティタイプは、最初の Sync API 呼び出しによって異なります。これらのエンティティタイプの詳細については、API Playground を参照してください。

    etag

    string

    バッチ内の最後のエンティティの etag。

    hasMore

    boolean

    取得するエンティティがさらにあるかどうかを指定します。

  • 転送されるデータのサイズを減らすために、Sync API は、制限されたサイズ (呼び出しによって定義される) のバッチでデータを返します。すべてのエンティティを取得するには、複数の呼び出しを行う必要があります。例: Space インスタンスには、アプリケーションが取得したい 250 件の課題が含まれています。バッチサイズが 100 の場合、アプリケーションは 3 回の呼び出しを行う必要があります。2 つの API リクエストの間にエンティティが更新されると、エンティティが複数回返される可能性があることに注意してください。

Sync API を使用してチャットメッセージを取得する

同期 API は、チャットメッセージでは少し異なる動作をします。メッセージを同期するアプリケーションの場合、メッセージの順序を保持することが重要です。課題は、チャットメッセージが更新されると、作成時に付与された etag ではなく、新しい etag が取得されることです。その結果、このメッセージは他のメッセージ (メッセージの作成と更新の間の間隔で作成される) の後に返されます。これは、アプリケーションが単に Sync API からのレコードを反復処理して、順序を乱さずにメッセージを 1 つずつ送信することはできないことを意味します。

この課題に対処するために、Space は最新のチャットメッセージ etag だけでなく、その作成時にメッセージに指定された最初の etag から始まるすべての etag 履歴を保存します。同時に、Space はメッセージテキストの履歴を保存せず、最新のテキストバージョンのみを保持します。以前の etag でメッセージをリクエストした場合でも、datetime および modType (CREATEDUPDATED、または ARCHIVED) フィールドはリクエストされた etag に対して正確ですが、最新バージョンのメッセージテキストを受け取ります。

チャットメッセージの Get sync batch 呼び出しは、data: ChannelItemSyncRecord フィールドを持つレコードを返します。data: ChannelItemSyncRecord フィールドは次のフィールドで構成されます。

フィールド

タイプ

説明

chat

ChannelItemRecord

idtext、その他のフィールドを含むチャットメッセージデータ。archived: Boolean フィールドは、modType = "ARCHIVED" 状態に加えて、メッセージが削除されたかどうかを示すことに注意してください。

etag

string

メッセージの etag。

modType

string

メッセージの状態: CREATEDUPDATED、または ARCHIVED (削除済み)。

チャットメッセージを取得する Sync API 呼び出しは、他の Space エンティティの場合と同じように見えます。唯一の違いは、応答で多少異なるデータ構造が得られることです。

spaceClient.chats.messages.syncBatch.getSyncBatch( batchInfo = SyncBatchInfo.SinceEtag( etag = latestEtag, batchSize = batchSize ), channel = ChannelIdentifier.Channel(ChatChannel.FromName("My chat channel")) ) { chatMessage { text() id() archived() created() edited() } etag() modType() }
GET https://mycompany.jetbrains.space/api/http/chats/messages/sync-batch?batchInfo={etag:0,batchSize:50}&channel=channel:name:My%20chat%20channel&$fields=data(chatMessage(text,id,archived,created,edited),etag,modType),etag,hasMore Authorization: Bearer here_goes_the_token Accept: application/json

メッセージ状態の仕組み

例を考えてみましょう。

  1. 12:00 - メッセージ A が作成されます (id = Aetag = 1text = abc)。

  2. 12:05 - メッセージ B が作成されます (id = Betag = 2text = def)。

  3. 12:10 - メッセージ C が作成されます (id = Cetag = 3text = ghi)。

  4. 12:15 - メッセージ B が更新されます (id = Betag = 4text = 123)。

この後、たとえば 12:20 で、Sync API を使用してすべてのメッセージを取得します: etag = 0Space は次のレコードを返します。

data.chatMessage.id

A

B

C

data.etag

1

2

3

data.modType

CREATED

CREATED

CREATED

data.chatMessage.text

ABC

123

data.chatMessage.created

12:00

12:05

12:10

data.chatMessage.edited

12:15

メッセージ B はすでに更新されているにもかかわらず、CREATED 状態で古い etag とともに返されます。これは、そのような場合に備えて、Sync API がレコードを 1 つに統合するためです。

ここで、3 つのメッセージすべてが作成された後、メッセージ B が更新される前に、12:13 で同期を実行したと想像してください (最新の etag は 3 で、メッセージ B のテキストは def です)。12:20 ではメッセージを更新したいため、etag = 3 で Sync API リクエストを送信します。この場合、Space は 1 つのレコードだけを返します。

data.chatMessage.id

B

data.etag

4

data.modType

UPDATED

data.chatMessage.text

123

data.chatMessage.created

12:05

data.chatMessage.edited

12:15

削除されたメッセージの場合、Space は常に空の文字列を含む ARCHIVED レコードを text として返します。

関連ページ:

チャットと通知

チャットは、同僚とコミュニケーションを取り、最新情報を入手するための主要な場所です。メッセンジャーとしてだけでなく、通知、リクエスト、アラートを受信するための個人の受信箱としても機能します。すべてのチャットアクティビティは次のように構成されます。会話チャンネル、通知フィード、ダイレクトメッセージング、会話チャンネル:チャネルは、特定のグループ向けに、または特定のトピックについて話し合うために作成されたグループチャットです。例: チームが共同作業するための専用チャネルを作成できます。チャネルはパ...

課題トラッカー

Space のすべてのプロジェクトには、課題追跡システムが組み込まれています。これは、プロジェクト参加者がバグやリクエストを追跡できるように設計されており、プロジェクトのライフサイクルのすべての段階を通じて、開発およびデバッグのプロセスがより透明で管理しやすくなります。Space の課題は、バグ、設計上の欠陥、製品の欠陥などの課題を表すことができる固有の記録です。また、何らかの機能強化や新機能を実装するための提案や要求を表すこともあります。課題を報告する場合、または変更をリクエストする場合は、課...

チームとメンバー

チームは、実際の組織構造を表すディレクトリです。フラットでシンプルなものもあれば、親チームと子チーム (サブチーム) による複雑なマルチレベル階層を持つこともできます。人は 1 つまたは複数のチームのメンバーになることができます。メインナビゲーションメニューからチームを選択します。組織のすべてのメンバーが表示されます。左側のサイドバーには、組織内のすべてのチームがリストされます。チームをクリックすると、そのメンバーが表示されます。チームを探す、メンバーを探す、チームの作成と管理、最終更新日: 2...

絵文字

絵文字を追加する:カスタム絵文字を追加するフィールドを持つオブジェクト::(必須)、:(必須)、引数なし絵文字の削除:絵文字を名前で削除するフィールドを持つオブジェクト::(必須)、引数なし絵文字の使用を記録する:絵文字の使用を記録し、頻繁に使用されるリストを更新しますフィールドを持つオブジェクト:: の配列 (必須)、引数なし絵文字が存在するかどうかを確認する:指定された絵文字名が存在するかどうかを確認する:(クエリ) (必須)

Space HTTP API

Space HTTP API を使用すると、チャット、チームディレクトリ、プロジェクト、ドキュメント、パッケージなどの任意の Space モジュールにプログラムでアクセスできます。特定の API リクエストの実行の詳細については、API 参照を参照するか、API Playground(下記を参照) を使用してください。HTTP API をすぐに使い始めるには、Space SDK を使用します。API Playground:API Playground を使用すると、次のことが可能になります。Spac...