위젯 집합의 OSDK와 API 접근

위젯 집합 개요의 Configure SDK에서 온톨로지와 사용할 리소스를 선택합니다.

위젯 집합에서 온톨로지 SDK를 구성하는 메뉴

API 활성화와 사용자 권한

온톨로지 호출에는 SDK 생성 외에 Ontology APIs 활성화도 필요합니다. Information Security Officer 기본 플랫폼 인스턴스 역할 또는 Enable widget set unscoped API access 워크플로를 부여하는 사용자 지정 플랫폼 인스턴스 역할로 수행할 수 있습니다.

실행 중 요청은 현재 사용자의 토큰과 권한을 따릅니다. API 활성화가 사용자의 리소스 접근 권한을 대신하지 않습니다.

생성 SDK 설치

기존 package.json의 dependencies에 다음 항목을 포함하고 설치합니다. 다른 의존성은 유지합니다.

{"dependencies":{"@custom-widget/sdk":"latest"}}

In Foundry로 만든 저장소의 .npmrc는 이미 SDK를 해석하도록 구성되어 있으므로 변경하지 않습니다.

Outside of Foundry로 만들었고 생성 시 OSDK 패키지를 만들지 않은 경우에는 프로젝트 루트의 .npmrc에 SDK registry를 구성합니다. 아래 호스트와 위젯 집합 RID를 실제 값으로 바꿉니다.

//<EXAMPLE>.palantirfoundry.com/artifacts/api/:_authToken=${FOUNDRY_TOKEN}
@custom-widget:registry=https://<EXAMPLE>.palantirfoundry.com/artifacts/api/repositories/<ri.widgetregistry..widget-set.LOCATOR>/contents/release/npm/

FOUNDRY_TOKEN은 비공개 환경변수로 공급합니다. .npmrc에는 ${FOUNDRY_TOKEN} 참조를 그대로 저장하며 실제 토큰 문자열로 치환하여 기록하지 않습니다.

런타임 클라이언트

baseUrl은 window.location.origin을 사용합니다. createFoundryWidgetTokenProvider는 위젯 런타임의 사용자 토큰 중계에 맞는 provider입니다.

import { createClient } from "@osdk/client";
import { $ontologyRid } from "@custom-widget/sdk";
import { createFoundryWidgetTokenProvider } from "@osdk/widget.client";

export const client = createClient(
  window.location.origin,
  $ontologyRid,
  createFoundryWidgetTokenProvider(),
);

SDK docs에서 선택한 리소스의 실제 API 이름과 호출 예를 확인합니다.

생성한 SDK의 자료형과 호출 예를 여는 SDK docs

액션 후 호스트 데이터 갱신

위젯이 OSDK 액션으로 객체 집합 매개변수의 데이터를 바꾸면 호스트의 데이터가 오래된 상태일 수 있습니다. refreshHostDataOnAction을 켜면 위젯에 전달된 객체 집합 매개변수를 호스트가 자동으로 갱신합니다. Workshop 제작자가 별도 동작을 추가할 필요는 없습니다.

새 위젯 집합은 plugin 수준에서 이 옵션이 기본 활성화됩니다. 기존 집합은 Vite plugin의 defaults에 지정할 수 있습니다. 프로젝트의 다른 설정과 plugin은 유지합니다.

import FoundryWidgetPlugin from "@osdk/widget.vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    FoundryWidgetPlugin({
      defaults: { refreshHostDataOnAction: true },
    }),
  ],
});

개별 위젯의 설정은 plugin 기본값보다 우선합니다. 다음은 한 위젯에서 자동 갱신을 끄는 구성 예입니다.

import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "myWidget",
  name: "My Widget",
  description: "An example widget",
  type: "workshop",
  refreshHostDataOnAction: false,
  parameters: {},
  events: {},
});

실제 위젯에서는 기존 parameters와 events를 유지하며 해당 옵션을 설정합니다.

허용 API

다음 Admin 엔드포인트는 사용자 위젯에서 사용할 수 있습니다.

Ontology APIs를 활성화하면 Ontologies와 Functions 네임스페이스의 모든 엔드포인트 및 Upload Media를 추가로 사용할 수 있습니다.

객체 집합 구독과 위 목록 밖의 API는 지원하지 않습니다. 외부 서비스는 허용된 함수나 webhook을 통해 요청을 감싸는 경로를 사용합니다.