초기화한 TypeScript 앱에 OSDK 추가

Developer Console 또는 로컬 @osdk/create-app CLI로 앱을 초기화할 때 OSDK를 넣지 않았다면 온톨로지 설정과 생성 패키지를 추가할 수 있습니다. 기존 앱의 Foundry URL과 OAuth 인증 구성을 유지하면서 PlatformClient를 온톨로지 Client로 바꾸는 작업입니다. 사용자 지정 빌드 구조는 파일 위치와 초기화 코드를 그 구조에 맞춥니다.

HTML 메타 태그

index.html의 기존 head 안에 다음 태그를 추가합니다.

<meta name="osdk-ontologyRid" content="%VITE_FOUNDRY_ONTOLOGY_RID%" />

빌드가 VITE_FOUNDRY_ONTOLOGY_RID를 치환하고 클라이언트 초기화 코드가 이 메타 태그를 읽습니다.

환경별 온톨로지 RID

프로젝트에 존재하는 .env.development, .env.production, .env.code-workspaces 등 각 환경 파일에 VITE_FOUNDRY_ONTOLOGY_RID를 설정합니다. 값은 Ontology Manager에서 확인합니다.

다음은 형식 설명용 가상 RID이며 실제 온톨로지 RID로 바꿉니다.

VITE_FOUNDRY_ONTOLOGY_RID=ri.ontology.main.ontology.11111111-1111-4111-8111-111111111111

온톨로지 RID는 앱의 식별 설정입니다. 패키지 다운로드용 비밀 토큰은 VITE_ 변수나 HTML 메타 태그에 넣지 않습니다.

client.ts 변경

기존 앱이 설정한 foundryUrl과 auth는 유지합니다. auth는 기존 OAuth 흐름이 제공하는 인증 객체 또는 토큰 제공자이며 createClient의 세 번째 인수로 전달합니다. 템플릿의 getMetaTagContent는 이름에 해당하는 메타 태그 값을 읽는 helper입니다.

client.ts에 다음 변경을 적용합니다.

-import { createPlatformClient, type PlatformClient } from "@osdk/client";
+import { createClient, type Client } from "@osdk/client";

+const ontologyRid = getMetaTagContent("osdk-ontologyRid");
-export const client: PlatformClient = createPlatformClient(foundryUrl, auth);
+export const client: Client = createClient(foundryUrl, ontologyRid, auth);

생성 SDK 패키지

Developer Console > Overview > Generated SDKs에서 앱의 SDK 패키지 이름을 확인하고 package.json의 기존 dependencies에 추가합니다.

아래 @example-osdk/sdk는 가상 패키지 이름이며 그대로 설치할 패키지가 아닙니다. 자신의 생성 패키지 이름과 사용할 버전으로 바꿉니다. latest는 최신 태그를 선택하는 예시입니다.

{
  "dependencies": {
    "@example-osdk/sdk": "latest"
  }
}

이 객체의 항목을 기존 파일에 병합하며 다른 의존성은 유지합니다.

로컬 초기화 앱의 .npmrc

Foundry 안에서 초기화한 저장소는 이 수동 레지스트리 설정을 건너뜁니다. 로컬 개발 환경에서 초기화한 저장소에는 OSDK 패키지의 레지스트리와 토큰 참조를 설정해야 합니다.

Generated SDKs에서 패키지 범위와 레지스트리 URL을 확인합니다. 범위 키에는 /sdk를 붙이지 않습니다. 다음 hostname, 패키지 범위와 저장소 RID는 가상 값입니다.

//hostname.palantirfoundry.com/artifacts/api/:_authToken=${FOUNDRY_TOKEN}
@example-osdk:registry=https://hostname.palantirfoundry.com/artifacts/api/repositories/ri.artifacts.main.repository.45660bd6-de33-442e-9f48-a0c02372b906/contents/release/npm

_authToken 앞에 백슬래시를 넣지 않습니다. 토큰 설정은 해당 호스트와 경로에 한정하여 다른 레지스트리에 전달되지 않도록 합니다.

.npmrc에는 실제 비밀값 대신 문자 그대로의 ${FOUNDRY_TOKEN}을 둡니다. 공백이 들어간 ${FOUNDRY TOKEN}은 다른 이름이므로 401 또는 403 인증 오류의 원인이 됩니다.

토큰은 개인 비밀정보 관리 경로로 현재 실행 환경에 주입한 뒤 설치합니다. 다음 Bash는 값이 없으면 중단하고 토큰 값 자체를 명령줄에 넣지 않습니다.

: "${FOUNDRY_TOKEN:?SDK를 읽을 수 있는 토큰을 실행 환경에 제공해야 합니다}"
export FOUNDRY_TOKEN
npm install

npm 404와 인증 오류

404가 나오면 요청이 실제 OSDK 패키지 레지스트리로 향하는지 확인합니다.

npm config get registry

전역 레지스트리만으로 결론 내리지 말고 프로젝트의 @scope:registry 값도 확인합니다. 범위별 레지스트리는 일반 registry보다 우선합니다. 프로젝트와 사용자 및 전역 .npmrc의 의도하지 않은 설정이 없는지 확인합니다.

401 또는 403은 토큰 변수 이름, 값의 주입 여부와 패키지 읽기 권한을 확인합니다. 토큰을 로그로 출력하여 확인하지 않습니다. TypeScript, Python과 Java 외의 언어를 사용하려면 OpenAPI 명세를 내려받아 해당 언어의 클라이언트를 생성할 수 있습니다.

Keyboard shortcuts