using-backstage-catalog

Backstage カタログのパターン

このスキルを使用する場面

• プラグインで、ref を指定して特定のエンティティ（Group、Component、User など）を取得する必要がある場合
• プラグインで、フィルターを使ってエンティティをクエリする必要がある場合（特定のチームが所有するすべての Component、指定したタイプのすべての Group など）
• プログラムから新しいカタログのロケーションを登録したり、エンティティを更新したり、ロケーションの登録を解除したりする必要がある場合
• フロントエンドコードとバックエンドコードの両方に適用できます。エントリーポイントは異なりますが、操作は同じです

適切なパターンの選択

フロントエンド（フロントエンドプラグインのコンポーネント内）

状況	パターン	リファレンス
ref で単一のエンティティを取得する	useApi(catalogApiRef).getEntityByRef(ref)	references/fetch-by-ref.md (フロントエンドのセクション)
フィルターを使ってエンティティをクエリする	useApi(catalogApiRef).getEntities({ filter })	references/query-entities.md (フロントエンドのセクション)
ロケーションを登録／更新／登録解除する	useApi(catalogApiRef).addLocation / refreshEntity / removeLocationById	references/register-entity.md (フロントエンドのセクション)

バックエンド（バックエンドプラグインまたはモジュール内）

状況	パターン	リファレンス
ref で単一のエンティティを取得する	catalog.getEntityByRef(ref, { credentials }) を catalogServiceRef 経由で呼び出す	references/fetch-by-ref.md (バックエンドのセクション)
フィルターを使ってエンティティをクエリする	catalog.getEntities({ filter }, { credentials }) を catalogServiceRef 経由で呼び出す	references/query-entities.md (バックエンドのセクション)
ロケーションを登録／更新／登録解除する	catalog.addLocation / refreshEntity / removeLocationById を catalogServiceRef 経由で呼び出す	references/register-entity.md (バックエンドのセクション)

2 つの呼び出しモード

• スタンドアロン（開発途中）：ユーザーが既存のプラグインを編集中です。上の状況一覧から適切なリファレンスを選び、適用します。
• スキャフォールド後（creating-backstage-plugin から呼び出される場合）：新たにスキャフォールドされたプラグインにパターンを適用します。各リファレンスの「スキャフォールド後の使用」セクションにファイルと挿入箇所が記載されています。frontend-template のスキャフォールドではフロントエンドのパターンを、backend-template のスキャフォールドではバックエンドのパターンを使用します。

よくある注意点

• フロントエンドのコードでは、catalogApiRef は @backstage/plugin-catalog-react から取得します。@backstage/catalog-client ではありません。後者はバックエンド用です。
• NFS プラグインでは、useApi 自体は @backstage/frontend-plugin-api から取得します。catalogApiRef はプラグイン固有であり、@backstage/plugin-catalog-react のままです。
• バックエンドのコードでは、@backstage/plugin-catalog-node の catalogServiceRef に依存します。これは認証とディスカバリーの設定が済んだ状態でカタログクライアントをラップし、BackstageCredentials を直接受け取ります。メソッドには { credentials }（BackstageCredentials オブジェクト）を渡します。{ token }（文字列）ではありません。受信した HTTP リクエストでは、httpAuth.credentials(req) で認証情報を取得します。サービス間の処理（スケジュールされたタスクや初期化時のフェッチ）では、auth.getOwnServiceCredentials() を使用します。手動で new CatalogClient(...) を作成しないでください。これは基盤となる API ですが、標準的なインターフェースはサービス参照です。
• getEntityByRef は Entity | undefined を返します。エンティティが削除されている場合や、参照が不正な場合があるため、必ず undefined のケースを処理してください。
• getEntities は { items: Entity[] } を返します。分割代入するか、.items にアクセスしてください。
• getEntities のフィルターは、1 つのオブジェクト内では AND 条件、オブジェクトの配列では OR 条件で結合されます。
• フロントエンド：レンダー中にフェッチしないでください。react-use の useAsync（マウント時または依存関係の変更時に自動フェッチ）か useAsyncFn（ボタン操作でフェッチ）でラップしてください。{ loading, error, data } のために useState を手動で設定しないでください。このフックは競合状態やアンマウント時のクリーンアップを適切に処理します。
• バックエンド：キャッシュなしで HTTP リクエストのたびにフェッチしないでください。頻繁にアクセスされる処理では、常に最新のデータが必要ない結果をメモ化するために coreServices.cache を使用してください。

UI の規約

可能な場合は、描画に @backstage/ui（Skeleton、Alert、Text、Flex、Button など）を使用してください。コンポーネントの一覧とスタイリングのガイダンスについては、using-backstage-ui スキルを参照してください。