creating-backstage-catalog-provider

Backstage Catalog Provider の作成

このスキルを使う場面

• 外部ソース（Azure DevOps、GitHub のトピック検索、社内のアセットレジストリ、JSON ファイルなど）からカタログエンティティを取り込むモジュールを構築する
• 既存の catalog-backend-module-* プラグインを編集する
• 取り込みを定期的に実行する（プロバイダーモデル）場合 — エンティティ定義ファイルを一度だけ処理する場合は、代わりに CatalogProcessor を作成する

作成するもの

カタログプロバイダーは、拡張ポイントにプロバイダーを登録するバックエンドモジュール（createBackendModule({ pluginId: 'catalog', ... })）です。プロバイダーモデルは 2 種類あります。データ量に応じて選択してください。

まずモデルを選ぶ：通常型かインクリメンタル型か

通常型の EntityProvider を使う場合...	IncrementalEntityProvider を使う場合...
エンティティの総数が少ない（多くても数百程度）	エンティティの総数が多い（数千以上）
全件をメモリに無理なく保持できる	全件をメモリに保持するのが現実的ではない
ソースから一度の往復（または数回）ですべてのスナップショットを取得できる	ソースがページネーション（カーソル／ページトークン／オフセットなど）に対応している
プロトタイプや POC を構築する	本番規模のカタログ向けにリリースする
更新頻度が低い	書き込み頻度が高い、または規模が大きい。インクリメンタル型ではバッチ処理、バックオフ、再試行に対応

2 種類のモデルは、異なる拡張ポイントに登録し、実行時の動作も異なります。

• 通常型は @backstage/plugin-catalog-node の catalogProcessingExtensionPoint に登録します。導入側で追加のインストールは不要です。
• インクリメンタル型は @backstage/plugin-catalog-backend-module-incremental-ingestion の incrementalIngestionProvidersExtensionPoint に登録します。導入側では catalogModuleIncrementalIngestionEntityProvider（バッチ処理を統括し、カタログデータベースを通じてカーソルを永続化するフレームワークモジュール）もインストールする必要があります。

最初にどちらを選ぶべきかわからない場合は、通常型を選んでください。後からインクリメンタル型へ移行する作業は機械的に行えます。ドメインのデータ取得ロジックはそのまま使い、フレームワークとの接続部分だけを変更します。

データ量が本当にわからない場合は、ユーザーに確認してください。おおよその目安は、エンティティが 500 件未満なら通常型で問題ありません。10,000 件を超える場合はインクリメンタル型が必須です。その中間の場合は、ソースがページネーションに対応しているか、今後どの程度増える見込みかを確認してください。

適切なパターンを選ぶ

構築するもの...	リファレンス
通常型の EntityProvider クラス（少量から中量向けのデフォルト）	references/entity-provider.md（通常型のセクション）
IncrementalEntityProvider クラス（大量向け）	references/entity-provider.md（インクリメンタル型のセクション）
どちらかのプロバイダーを接続するモジュール	references/module-registration.md

2 種類の呼び出しモード

• 単独：既存の catalog-backend-module-* プラグインを編集します。
• スキャフォールド後（catalog-provider-module 向けに creating-backstage-plugin から呼び出される場合）：プロバイダークラスとモジュール登録の両方のファイルをまとめてスキャフォールドします。

よくある注意点

• プロバイダーの getProviderName() は、カタログ内で一意である必要があります（通常型と増分型の両方で同じルールが適用されます）。安定した名前を使用してください。出力されたエンティティはこの名前でプロバイダーに紐付けられるため、名前を変更すると孤立します。
• 通常型プロバイダー： applyMutation({ type: 'full', entities }) は、プロバイダーが所有するエンティティ一式を置き換えます。applyMutation({ type: 'delta', added, removed }) は個々のエントリーを追加・削除します。変更を段階的にしか把握できない場合に便利です。これは デルタミューテーション であり、IncrementalEntityProvider モデルとは異なることに注意してください。
• 通常型プロバイダー： connect() が実行されるまで接続は利用できません。connect() の前に実行される可能性のあるメソッドでは、this.connection が undefined でないか確認してください。
• 通常型プロバイダー： connect() 内で外部システムから直接データを取得しないでください。SchedulerServiceTaskRunner を受け取り、connect() 内で this.schedule.run({ id, fn }) を呼び出してください。そうすることで、処理が定期的に実行され、再起動後も継続されます。
• 増分型プロバイダー： イテレーションループはフレームワークが管理します。next(context, cursor?) は1ページを返します。フレームワークは、前回返されたカーソルを使ってこれを繰り返し呼び出し、状態をカタログデータベースに永続化します。独自の更新処理をスケジュールしないでください。
• 増分型プロバイダー： 導入する側は、モジュールに加えて @backstage/plugin-catalog-backend-module-incremental-ingestion の catalogModuleIncrementalIngestionEntityProvider を必ずインストールする必要があります。この前提条件をモジュールの README に記載してください。
• catalogProcessingExtensionPoint はライブラリパッケージの @backstage/plugin-catalog-node から提供されます。incrementalIngestionProvidersExtensionPoint は @backstage/plugin-catalog-backend-module-incremental-ingestion から提供されます。モジュールから @backstage/plugin-catalog-backend に依存しないでください。これはホストプラグインです。