Streaming-API

Durch die Verwendung des Streaming-APIs können verschiedene Daten (z. B. darüber, dass neue Beiträge geschrieben wurden, neue Direktnachrichten eingetroffen sind, Benachrichtigungen über einen neuen Follower, usw) in Echtzeit empfangen werden und dann basierend auf diesen verschiedene Aktionen getätigt werden.

Eine Verbindung zum Stream aufbauen

Um das Streaming-API zu benutzen, muss zuerst eine Verbindung zu Misskey's websocket Server aufgebaut werden.

Websocket-Verbindung zu einer URL mit folgendem Format:

wss://{host}/streaming?i={token}

Hier,

• Ersetze Sie {host} durch den Host des Servers, mit dem Sie eine Verbindung herstellen wollen.
• Ersetzen Sie „{token}“, durch das Zugriffstoken des Benutzers.

Eine Verbindung zum Stream kann durch die später erläuterte API oder durch das Abbonieren individueller Beiträge getätigt werden. Jedoch können zu diesem Zeitpunkt noch keine Informationen über Chroniken wie das Eintreffen neuer Beiträge empfangen werden. Um dies zu ermöglichen, müssen Verbindungen zu später erläuterten Kanälen aufgebaut werden.

Alle Nachrichten an den sowie vom Stream sind in JSON-Format.

Kanäle

Innerhalb des Misskey Streaming-APIs existiert das Konzept von Kanälen. Diese werden zur Abspaltung der Informationen, die erhalten werden sollen, verwendet. Wird eine Verbindung zum Misskey Stream aufgebaut, so ist es noch nicht möglich, sofort Echtzeit-Aktualisierungen zu empfangen. Durch den Verbindungsaufbau zu Kanälen des Streams wird beidseitige Kommunikation bezüglich Informationen dieses Kanals ermöglicht.

Im folgenden Abschnitt wird beschrieben, wie Sie die Kanäle nutzen können. Um zu sehen, welche Kanäle verfügbar sind, siehe Kanalliste.

Verbindungen zu Kanälen aufbauen

Um eine Verbindung zu einem Kanal aufzubauen, sende die folgende Nachricht:

{
    type: 'connect',
    body: {
        channel: 'xxxxxxxx',
        id: 'foobar',
        params: {
            ...
        }
    }
}

Hier,

• steht channel für den Namen des Kanals, zu dem eine Verbindung aufgebaut werden soll.チャンネル一覧を参照してください。
• steht id für eine einzigartige ID zur Kommunikation mit diesem Kanal. Da durch den Stream viele verschiedene Nachrichten erhalten werden können, ist eine Zuordnung, zu welchen Kanal eine Nachricht gehört, notwendig. Diese ID kann eine UUID oder etwas wie der Wert eines Zufallszahlengenerators sein.
• steht params für die Parameter zum Verbindunsgaufbau. Je nach Kanal können die verfügbaren Parameter abweichen. Bei Kanälen, die keine Parameter akzeptieren, kann dieses Attribut ausgelassen werden.

Verarbeitung von eintreffenden Nachrichten der Kanäle

Beispielsweise wird bei Erstellung eines neuen Beitrags auf einer Chronik von einem Kanal eine Nachricht ausgelöst. Durch die Verarbeitung solcher Nachrichten ist es möglich, in Echtzeit über die Erstellung eines neuen Beitrags zu erfahren.

Sendet ein Kanal eine Nachricht, so wird vom Stream folgendes JSON-Objekt empfangen:

{
    type: 'channel',
    body: {
        id: 'foobar',
        type: 'something',
        body: {
            some: 'thing'
        }
    }
}

Hier,

• steht id für die zum Verbindungsaufbau gewählte ID, die zuvor erläutert wurde. Hierdurch wird eine Zuordnung, welche Nachricht zu welchen Kanal gehört, ermöglicht.
• steht type für die Art der Nachricht. Je nach Kanal können die Arten der Nachrichten, die von einem Kanal empfangen werden, abweichen.
• steht body für den Inhalt der Nachricht. Je nach Kanal kann der Inhalt der Nachrichten, die von einem Kanal empfangen werden, abweichen.

Nachrichten an Kanäle senden

Je nach Kanal kann es möglich sein, nicht nur Nachrichten vom Kanal zu empfangen, sondern auch Nachrichten an diesen zu senden, die dann unterschiedliche Aktionen auslösen können.

Um eine Nachricht an einen Kanal zu senden, sende folgendes JSON-Objekt an den Stream:

{
    type: 'channel',
    body: {
        id: 'foobar',
        type: 'something',
        body: {
            some: 'thing'
        }
    }
}

Hier,

• steht id für die zum Verbindungsaufbau gewählte ID, die zuvor erläutert wurde. Hierdurch wird festgelegt, an welchen Kanal diese Nachricht gesendet werden soll.
• steht type für die Art der Nachricht. Je nach Kanal können die Arten der Nachrichten, die an einen Kanal gesendet werden können, abweichen.
• steht body für den Inhalt der Nachricht. Je nach Kanal kann der Inhalt der Nachrichten, der an einen Kanal gesendet werden kann, abweichen.

Verbindungen zu Kanälen trennen

Um die Verbindung zu einem Kanal zu trennen, sende die folgende Nachricht:

{
    type: 'disconnect',
    body: {
        id: 'foobar'
    }
}

Hier,

• steht id für die zum Verbindungsaufbau gewählte ID, die zuvor erläutert wurde.

Beitragserfassung

Misskey stellt eine sogenannte Beitragserfassung zur Verfügung. Hierdurch können dem angegebenen Beitrag zugehörige Events über den Stream empfangen werden.

Sei beispielsweise eine Situation, in der einem Benutzer eine Chronik angezeigt wird. Angenommen, jemand reagiert auf einen der Beiträge in der Zeitleiste. Der Client kann jedoch nicht wissen, dass auf einen Beitrag reagiert wurde, sodass es nicht möglich ist, die Reaktion in Echtzeit in der Zeitleiste anzuzeigen.

Um dieses Problem zu lösen, wurde die Funktionalität der Beitragserfassung implementiert. Wird ein Beitrag erfasst, so werden verschiedene diesem Beitrag zugeordnete Events in Echtzeit übermittelt, um bei einer Veränderung diese sofort auf der Chronik anzeigen zu können.

Nachfolgend eine Anleitung zur Verwendung der Capture Post-Funktion. Welche Erfassungsereignisse verfügbar sind, finden Sie unter Liste der Erfassungsereignisse.

Einen Beitrag erfassen

Um einen Beitrag zu erfassen, sende folgende Nachricht an den Stream:

{
    type: 'subNote',
    body: {
        id: 'xxxxxxxxxxxxxxxx'
    }
}

Hier,

• id enthält die id des Beitrags der erfasst werden soll.

Sobald diese Nachricht gesendet wurde wird dieser Beitrag von Misskey erfasst und es können von nun an diesen Beitrag betreffende Events empfangen werden.

Beispielsweise wird das folgende Event empfangen, sobald einem erfassten Beitrag eine Reaktion hinzugefügt wurde:

{
    type: 'noteUpdated',
    body: {
        id: 'xxxxxxxxxxxxxxxx',
        type: 'reacted',
        body: {
            reaction: 'like',
            userId: 'yyyyyyyyyyyyyyyy'
        }
    }
}

Hier,

• das id-Attribut in body enthält die ID des Beitrags, der das Event ausgelöst hat.
• das type-Attribut in body die Art des Events.
• das body-Attribut von body enthält weitere Informationen über das Event.

Beitragserfassung aufheben

Sobald ein Beitrag nicht mehr auf der Chronik angezeigt wird und somit diesen Beitrag betreffende Events nicht mehr benötigt werden, bitten wir um die Aufhebung der Erfassung dieses Beitrags.

Sende die folgende Nachricht:

{
    type: 'unsubNote',
    body: {
        id: 'xxxxxxxxxxxxxxxx'
    }
}

Hier,

• id enthält die id des Beitrags, für den Erfassung aufgehoben werden soll.

Sobald diese Nachricht versendet wurde, werden mit diesem Beitrag verbundene Events nicht mehr empfangen.