엔티티 표시

엔티티 표시 (Entity Presentation)

카탈로그 엔티티가 Backstage 인터페이스 전체에서 어떻게 표시되는지 제어하는 Entity Presentation API를 설명하는 문서예요.

출처: 문서

본문

Entity Presentation API는 카탈로그 엔티티가 Backstage 인터페이스 전체에서 어떻게 표시되는지 제어해요. component:default/my-service 같은 원시 엔티티 ref를 렌더링하는 대신, 이 API는 metadata.title과 spec.profile.displayName 같은 필드에서 사람이 읽기 좋은 표시 이름을 해석해요.

엔티티 이름 표시하기

컨텍스트에 따라 엔티티 이름을 표시하는 방법은 여러 가지가 있어요.

EntityDisplayName 컴포넌트

React 컴포넌트에 가장 간단한 옵션이에요. 선택적 아이콘과 툴팁이 있는 스타일된 엔티티 이름을 렌더링해요.

import { EntityDisplayName } from '@backstage/plugin-catalog-react';<EntityDisplayName entityRef="component:default/my-service" />;

엔티티 ref 문자열, Entity 객체, 또는 CompoundEntityRef를 전달할 수 있어요. 컴포넌트는 선택적 hideIcon과 disableTooltip props를 지원해요.

useEntityPresentation 훅

React 컴포넌트에서 원시 표시 데이터에 접근해야 할 때, 예를 들어 사용자 지정 레이아웃에서 제목을 렌더링하려면 이 훅을 사용해요.

import { useEntityPresentation } from '@backstage/plugin-catalog-react';function MyComponent({ entityRef }: { entityRef: string }) {  const { primaryTitle, secondaryTitle, Icon } =    useEntityPresentation(entityRef);  return (    <span>      {Icon && <Icon fontSize="inherit" />}      {primaryTitle}    </span>  );}

훅은 EntityPresentationApi를 구독하고, 백그라운드에서 추가 데이터가 조회됨에 따라 시간이 지나며 업데이트될 수 있는 스냅샷을 반환해요.

API를 직접 사용하기 (async, 비-React에 선호)

await할 수 있는 비-React 비동기 컨텍스트(데이터 로더, useAsync 콜백, 이벤트 핸들러 등)에서는 .promise와 함께 entityPresentationApiRef API를 직접 사용해 가장 풍부한 표시를 얻어요.

const presentation = await entityPresentationApi.forEntity(entity, {  defaultKind: 'group',}).promise;const title = presentation.primaryTitle;

.promise 경로는 카탈로그에서 조회된 데이터를 포함할 수 있는 완전한 표시(presentation)로 해석돼요. 이것은 비동기 컨텍스트가 가능할 때마다 선호되는 접근 방식이에요.

entityPresentationSnapshot 헬퍼 (동기 대체)

동기 반환 값이 필요하고 await이 불가능한 경우(정렬 비교자, 열 팩토리, 필터 콜백 등)에는 entityPresentationSnapshot을 대체로 사용해요. Entity, CompoundEntityRef, 또는 문자열 ref 입력을 받고, 사용 가능할 때 표시 API를 사용하며 그 외에는 defaultEntityPresentation로 대체해요.

import {  entityPresentationSnapshot,  entityPresentationApiRef,} from '@backstage/plugin-catalog-react';// In a column factory or sort comparator where you have// the API instance (or undefined if not registered):const title = entityPresentationSnapshot(  entity,  {    defaultKind: 'Component',  },  entityPresentationApi,).primaryTitle;

이 함수는 동기적이므로 표시 API의 캐시된 데이터를 사용해요. 엔티티를 이전에 본 적이 있다면 스냅샷에는 완전히 해석된 제목이 포함되며, 그렇지 않으면 ref만으로 추출할 수 있는 것으로 대체돼요.

엔티티 표시 사용자 지정하기

엔티티가 어떻게 렌더링되는지 사용자 지정하려면 EntityPresentationApi 인터페이스의 나만의 구현을 제공하고 앱의 API 팩토리에 등록해요.

import {  entityPresentationApiRef,  type EntityPresentationApi,} from '@backstage/plugin-catalog-react';import { createApiFactory } from '@backstage/core-plugin-api';const myPresentationApi: EntityPresentationApi = {  forEntity(entityOrRef, context) {    // Return an EntityRefPresentation with snapshot, update$, and promise  },};createApiFactory({  api: entityPresentationApiRef,  deps: {},  factory: () => myPresentationApi,});

표시 스냅샷에는 primaryTitle, 툴팁용 선택적 secondaryTitle, 선택적 Icon 컴포넌트가 포함돼요. update$ 관찰 가능 항목을 통해 시간이 지나며 업데이트된 스냅샷을 내보낼 수도 있어요.

humanizeEntityRef에서 마이그레이션하기

humanizeEntityRef와 humanizeEntity 함수는 더 이상 사용되지 않아요(deprecated). 이들은 축약된 엔티티 ref 문자열만 생성하며 metadata.title이나 spec.profile.displayName에서 표시 이름을 해석하지 않아요.

다음과 같이 교체하세요.

더 알아보기 (Learn more)