参照機能の技術情報
Fedibirdの参照機能について、とにかく技術情報をどこかに書いておく必要があるので、暫定でここに書き下しておきます(固定化フラグ)。
ActivityPubにおける参照
Noteのreferencesコレクションとして、Noteとして解釈できるオブジェクトを列記したものです。
https://fedibird.com/@noellabo/108127694484335642
備考
- ここでは数件インラインで表現していますが、followersやoutboxなどと同様の一般的なCollectionの記法となります。firstからnextを辿ってitemsを取得してください。
- Fedibirdでは1投稿あたり100件に制限しています
REST APIにおける参照
投稿への参照付与
API
- POST /api/v1/statuses
追加のパラメータ | 型 | 意味 |
---|---|---|
status_reference_ids[] | array of string | Array of local status IDs in the database. |
status_reference_urls[] | array of string | Array of status uris. |
説明
投稿本文にURLを記載すると参照として抽出されますが、パラメータとして別途参照を与えることができます。通常はサーバ内表現の投稿ID(status_reference_ids)を使うことになると思いますが、複数サーバ・複数アカウントを同時に扱えるクライアントからは、投稿URLを与えられるパラメータ(status_reference_urls)があるので、そちらの方が便利かもしれません。
投稿の一括取得
API
- GET /api/v1/statuses
パラメータ | 型 | 意味 |
---|---|---|
ids[] | array of string | Array of local status IDs in the database. |
説明
参照関連のREST応答では、Statusの内容を伴わずIDだけ列挙するものが多いので、それらを一括取得するために使います。
投稿の削除と下書きに戻す
API
- DELETE /api/v1/statuses/:id
説明
レスポンスにstatus_reference_ids
が追加されます。
この値を無視すると、再投稿時に情報が失われます。参照について特別な処理をしない場合でも、この値を保持し、投稿時に渡すようにしてください。
なお、投稿時と異なるセッションではこれらのidのエンティティが未取得の場合がありますので、投稿の一括取得のAPIを利用して未取得のidについて取得すると良いでしょう。
投稿の参照の取得
API
- GET /api/v1/statuses/:id/context
パラメータ | 型 | 意味 |
---|---|---|
with_reference | boolean | 未指定時はfalse。指定するとreferencesを切り離して返す |
説明
context APIは通常、ancestorsとdescendantsを返しますが、投稿に参照が含まれる場合、未対応クライアントの互換のためにancestorsにreferencesをミックスして返します。with_reference
パラメータをtrueにすると、ancestorsとreferencesは分離され、descendantsとあわせて3つがそれぞれ返されます。
対応クライアントを作成する場合、with_reference
パラメータをtrueに指定して、取得したreferencesを一覧するカラム等を作成し、本文中の互換リンクをクライアントのカラムに誘導するリンクへ置き換えることが期待されます。
なお、このAPIによる参照は、セルフリプライの参照をマージしたものが返されます。
投稿毎の参照は各投稿のstatus_reference_ids
にローカルIDを列記する形で提供されています。
投稿を参照している投稿の一覧を取得
API
- GET /api/v1/statuses/:id/referred_by
パラメータ | 型 | 意味 |
---|---|---|
id | string | Local ID of a status in the database. |
説明
逆参照を取得します。Statusエンティティの配列を返します。
通知
API
- POST /api/v1/push/subscription
- GET /api/v1/push/subscription
- PUT /api/v1/push/subscription
追加のパラメータ | 型 | 意味 |
---|---|---|
data[alerts][status_reference] | boolean | Receive status reference notifications? |
説明
参照通知を購読するための追加パラメータです。
Instanceエンティティ
追加の属性 | 型 | 意味 |
---|---|---|
configuration.status_references.max_references | number | 投稿ごとの最大参照数 |
fedibird_capabilities | array of string | status_reference を含んでいれば、参照機能をサポートしている |
configuration: { status_references: { max_references: 100 } }, fedibird_capabilities: [ "status_reference" ],
Statusエンティティ
追加の属性 | 型 | 意味 |
---|---|---|
status_reference_ids | array of string | Array of references post ids |
status_references_count | number | How many references this post has linked. |
status_referred_by_count | number | How many refererred by posts has linked. |
{ (snip...), status_reference_ids: ["108127691208762426", "108127665293086217", "108127467700309922"], status_references_count: 3, status_referred_by_count: 2 }
Notificationエンティティ
参照通知
Type属性がstatus_reference
で、status属性を伴うエンティティタイプが追加されます。status属性は参照先ではなく、リンクした元投稿となります。
『この投稿から参照されました』という意味になります。
設定値
Initial State
Initial stateとして、下記の値がWebUI向けに提供されます。
追加の属性 | 型 | 意味 |
---|---|---|
enable_status_reference | boolean | 参照機能を有効にしているか(ユーザー) |
match_visibility_of_references | boolean | フォロワー限定の参照を追加するときに、投稿の公開範囲を一致させる動作をデフォルトとするか(ユーザー) |
post_reference_modal | boolean | 参照を含む投稿を投稿する時に確認ダイアログを表示するか(ユーザー) |
add_reference_modal | boolean | フォロワー限定の参照を追加する時に確認ダイアログを表示するか(ユーザー) |
unselect_reference_modal | boolean | 参照の解除時に確認ダイアログを表示するか(ユーザー) |
status_references.max_references | number | 投稿ごとの最大参照数(サーバ) |
互換機能と専用対応
[参照]リンク
本文の末尾に[参照]
という投稿元サーバの参照の公開ページへのリンクが付与されます。reference-link-inline
というclassが指定されたspanタグに囲まれていますので、リモートサーバやクライアントで参照に対応する際は、このリンクを含むspanを除去し、それぞれで提供する専用のものに置き換えてください。
<span class="reference-link-inline"><a href="https://〜"> [参照]</a></span>
参照の公開ページ
参照リンクからたどれる公開ページは、投稿にリンクした参照先の投稿が、新しい順に並んで表示されます。
投稿元のサーバにログインしているユーザーは、アカウントフォロー関係やミュート・ブロック関係に基づき、表示可能な投稿、非表示にする投稿が選択されます。
ログインしていない場合は、フォロワー限定の投稿は表示されませんが、ミュートやブロックは未指定となるため、意図しない投稿者の投稿がみえる場合があります。
様々な条件で、表示対象が一件もない場合、投稿が存在しないエラーページが表示されます。
なお、このページにapplication/activity+json
をリクエストすると、referencesコレクションにリダイレクトされます。
OGPとプレビューカード
前記の公開ページはOGPにて参照の概要を提供しています。他のリンクがなければ、Mastodonはこのリンク先から取得したOGPに基づきプレビューカードを作成しますので、クライアントはこれを表示するという選択肢もあります。
ただし、プレビューカードは個別の事情を反映しておらず、公開範囲やミュート・ブロックを反映することができないため、クライアントサイドでカスタム表示した方がより優れた表示が可能となります。
セルフリプライと参照
セルフリプライは同じ投稿者が自身の投稿にリプライしたもので、通常のリプライとしての扱いではなく、Mastodonによって起点となる投稿と同等の扱いを受けるという特徴があります。
本参照機能では、セルフリプライによる一連のスレッドで参照を共有(マージ)します。このことにより、参照は追記が可能になります。context APIにて取得できるreferencesは、マージされたものが返されます。