Bluesky のカスタムフィードの仕組みとデバッグ方法
Bluesky のカスタムフィードの構成要素(ジェネレーターのレコード、サービス DID、#bsky_fg サービス、スケルトンと完成したフィード)と、各ヘルスチェックの直し方を説明します。
カスタムフィードの構成要素
カスタムフィードは、別々の場所にある 2 つの部分でできています。
- レコード(
app.bsky.feed.generator):作成者のアカウントにあり、名前、説明、アバター、そしてフィードを配信するフィードジェネレーターを指すdidフィールドを持ちます。アドレスはフィードの AT URIat://<作成者>/app.bsky.feed.generator/<rkey>、bsky.app のリンクはhttps://bsky.app/profile/<作成者>/feed/<rkey>です。 - フィードジェネレーター:その DID(
did:webまたはdid:plc)で識別されるサーバーです。DID ドキュメントには id が#bsky_fg、type がBskyFeedGeneratorのサービスがあり、そのserviceEndpointがサーバーの https アドレスです。
1 つのジェネレーターが、それぞれのレコードを持つ複数のフィードを配信できます。
スケルトンと完成したフィード
フィードを開くと、アプリは Bluesky の AppView に app.bsky.feed.getFeed を問い合わせます。AppView はレコードを読み、ジェネレーターの DID を解決し、#bsky_fg のエンドポイントを見つけて、そこで app.bsky.feed.getFeedSkeleton を呼び出します。ジェネレーターはスケルトン、つまり投稿の URI の一覧だけを返します。
{
"feed": [
{ "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
],
"cursor": "1731567000000"
}AppView はそれを完成させます。各投稿、作者、数値を取得し、ブロック、ミュート、ラベルを適用して、完全な投稿を返します。閲覧者がログインしていない限り、ジェネレーターには誰がフィードを読んでいるか分かりません。ログインしている場合は、その人を示すトークンがリクエストに付きます。
AppView は各ジェネレーターの状態も追跡します。isOnline は最近接続できたこと、isValid は応答の形式が正しかったことを示します。フィードインスペクターは両方を表示します。
DID ドキュメント
did:web の場合、ドキュメントは https://<ホスト>/.well-known/did.json で配信されます。did:plc の場合は PLC ディレクトリが保持します。最小限の例:
{
"@context": ["https://www.w3.org/ns/did/v1"],
"id": "did:web:feed.example.com",
"service": [
{
"id": "#bsky_fg",
"type": "BskyFeedGenerator",
"serviceEndpoint": "https://feed.example.com"
}
]
}ジェネレーターは app.bsky.feed.describeFeedGenerator にも、同じ DID と配信するすべてのフィードの AT URI で応答する必要があります。
ヘルスチェックの手順
インスペクターのヘルスチェックは求められたときだけ実行し、AppView と同じ経路をたどります。
- サービス DID:レコードの
didは、ホスト名のみ(ポートやパスなし)のdid:webかdid:plcでなければなりません。そうでなければ、正しい DID でレコードを公開し直してください。 #bsky_fgサービス:DID ドキュメントが存在し、idが DID と一致する正しい JSON で、https のエンドポイントを持つ typeBskyFeedGeneratorの#bsky_fgサービスがある必要があります。describeFeedGenerator:GET <エンドポイント>/xrpc/app.bsky.feed.describeFeedGeneratorが、サービス DID と同じdidとfeedsの一覧を含めて 200 で応答する必要があります。- フィードが載っている:フィードの AT URI がその
feeds一覧にあるべきです。ない場合は注意になります。一覧に載せていないフィードを配信するジェネレーターもあります。 getFeedSkeleton:GET <エンドポイント>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1がfeed配列を含めて 200 で応答する必要があります。401 は、フィードがログインした閲覧者を必要とすることを意味します。アプリでは動作しますが、ログインしていない読者やインスペクターのプレビューでは表示されません。
各リクエストの上限は 4 秒・64 KB で、かかった時間を表示します。リクエストは安全チェックを通ります。ポート 443 の https のみで、プライベートやローカルのアドレスには決して送りません。そのため、家庭内ネットワーク上や localhost へのトンネルの背後にあるジェネレーターは、アプリが公開アドレス経由で接続できても、チェックに失敗します。
よくある直し方
- オフラインだがサーバーは動いている:DID ドキュメントのエンドポイント(入力ミス、
https://ではなくhttp://、余分なパス)と、そのホストに対して証明書が有効かを確認してください。 - 有効が false:スケルトンは
{ "post": "<at uri>" }の要素からなるfeed配列を持つオブジェクトでなければなりません。余分なフィールドは問題ありませんが、別の形式は不可です。 - スケルトンは空でないのにプレビューが空:返された投稿が削除されている、ブロックや削除されたアカウントのものである、またはログインしている人にだけ公開している作者のものである可能性があります。
- 動いていたのに止まった:ホストを移した
did:webのジェネレーターは DID ドキュメントの更新が、did:plcのジェネレーターは PLC 操作が必要です。
AT Protocol のカスタムフィードのチュートリアルと Bluesky のスターターキットで作り方を学べます。Bluesky.bot はボットのフィードのために独自のジェネレーターを運用しており、その DID ドキュメントは /.well-known/did.json にあります。