Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Developer Console 앱의 Marketplace 배포

Marketplace는 Developer Console 앱 또는 앱 소스 저장소를 다른 Foundry 환경에 설치할 수 있습니다. 목적에 따라 패키징 대상을 선택합니다.

방식사용할 때
앱 패키징메타데이터, OAuth 클라이언트와 배포 웹사이트를 함께 전달. Production 또는 Singleton 제품의 배포 앱에 권장
소스 패키징설치 대상에서 새 앱을 만들고 코드를 수정하는 템플릿과 교육 또는 Bootstrap 용도
앱과 소스 함께웹 자산이 아직 없는 OAuth 클라이언트를 먼저 설치하고 이후 코드에서 사이트를 게시할 때 사용 가능

Production에서는 설치 앱이 패키징한 웹 자산을 사용하므로 함께 넣은 소스를 바꾸기만 해서는 그 웹사이트가 바뀌지 않습니다.

앱에 포함되는 것

앱 패키징은 다음을 포함합니다.

  • 웹사이트의 정적 자산과 CSP. 가장 최근에 배포한 자산을 우선하며 배포 자산이 없으면 가장 최근 미배포 자산을 사용합니다.
  • 앱 이름, 설명과 구성 메타데이터
  • OAuth 클라이언트 유형, grant와 리다이렉트 URL
  • Ontology SDK 및 Platform SDK 리소스 접근 제한

Foundry DevOps에서 Developer Console 앱을 제품 출력으로 추가합니다. 의존성은 제한에 포함한 온톨로지 엔터티 및 기반 리소스와 프로젝트, 그리고 하위 도메인이나 보안 표지 같은 설치 매개변수입니다.

설치와 도메인 승인

설치하면 앱 리소스와 OAuth 구성을 만듭니다. 웹사이트 하위 도메인은 설치 입력으로 새 값을 정하며 Information Security Officer 등의 추가 승인이 필요할 수 있습니다.

설치 뒤 Developer Console의 Website hosting에서 도메인을 승인받아야 웹사이트에 접근할 수 있습니다.

온톨로지 엔터티를 함께 설치하면 Always install source Ontology API names를 선택하여 원본 API 이름을 유지합니다. Bootstrap 모드에서 같은 이름이 있으면 Truck이 Truck_1로 바뀌는 등 충돌 회피 이름이 생길 수 있으며 컴파일된 OSDK 코드는 이를 자동으로 따라가지 않습니다.

Compass 권한과 업그레이드

Compass 관리 권한이 제공되는 인스턴스는 앱도 다른 설치 리소스와 같은 대상 위치에 만듭니다. 원본 앱을 Compass로 이전해도 기존 설치는 자동 이전하지 않습니다. 각 설치에서 권한 이전을 수행하며 잠금 상태라면 먼저 해제를 요구할 수 있습니다.

설치 앱을 업그레이드할 때는 원본 앱을 바꾸고, 웹 자산이면 Developer Console에서 먼저 배포한 뒤 새 DevOps 제품 버전을 만듭니다. DevOps는 가장 최근 배포 자산을 선택합니다.

자동으로 바꾸는 앱 설정

빌드한 웹 자산을 설치할 때 다음 설정은 대상 환경 값으로 바꿀 수 있습니다.

  • Foundry URL
  • OAuth client ID
  • OAuth redirect URL
  • Ontology RID
  • Ontology API 이름

앱이 값을 번들 코드에 고정하지 않고 index.html의 메타 태그에서 읽어야 자동 매핑이 동작합니다. @osdk/create-app 2.1.3 이상 또는 Foundry VS Code 작업 공간에서 만든 앱은 이 방식을 기본으로 구성합니다.

객체 유형과 액션 같은 엔터티의 API 이름은 위의 온톨로지 자체 이름과 다르며 자동 매핑하지 않습니다.

이전 앱의 메타 태그

TypeScript OSDK 2.x를 사용해야 합니다. 1.x라면 SDK 이전을 먼저 수행합니다. index.html의 head에 다음 네 태그를 추가합니다.

<meta name="osdk-clientId" content="%VITE_FOUNDRY_CLIENT_ID%" />
<meta name="osdk-redirectUrl" content="%VITE_FOUNDRY_REDIRECT_URL%" />
<meta name="osdk-foundryUrl" content="%VITE_FOUNDRY_API_URL%" />
<meta name="osdk-ontologyRid" content="%VITE_FOUNDRY_ONTOLOGY_RID%" />

client.ts는 마지막에 있는 해당 메타 태그를 읽고, 값이 비어 있거나 빌드 placeholder가 남으면 명확히 실패하게 작성합니다.

import { createClient, type Client } from "@osdk/client";
import { createPublicOauthClient, type PublicOauthClient } from "@osdk/oauth";

function getMetaTagContent(tagName: string): string {
    const elements = document.querySelectorAll(`meta[name="${tagName}"]`);
    const element = elements.item(elements.length - 1);
    const value = element ? element.getAttribute("content") : null;
    if (value == null || value === "") {
        throw new Error(`Meta tag ${tagName} not found or empty`);
    }
    if (value.match(/%.+%/)) {
        throw new Error(
            `Meta tag ${tagName} contains placeholder value. Add ${value.replace(/%/g, "")} to your .env files`,
        );
    }
    return value;
}

const foundryUrl = getMetaTagContent("osdk-foundryUrl");
const clientId = getMetaTagContent("osdk-clientId");
const redirectUrl = getMetaTagContent("osdk-redirectUrl");
const ontologyRid = getMetaTagContent("osdk-ontologyRid");

export const auth: PublicOauthClient = createPublicOauthClient(
    clientId,
    foundryUrl,
    redirectUrl,
);

export const client: Client = createClient(foundryUrl, ontologyRid, auth);

환경 파일에는 실제 온톨로지 RID를 추가합니다. 아래는 형식 설명용 가상 값입니다.

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

다른 메타 태그에 대응하는 환경 값도 기존 앱 설정대로 유지합니다. 비밀 토큰과 client secret은 이 공개 HTML 설정에 넣지 않습니다.

패키징 제약

  • 기밀 클라이언트는 패키징할 수 있지만 대상에서 OAuth & restrictions > Rotate secret으로 새 비밀값을 만들어야 합니다.
  • 독립 OAuth 클라이언트는 Marketplace 패키징을 지원하지 않습니다. Unrestricted 앱을 사용합니다.
  • 앱 OSDK에 포함한 함수는 latest 버전을 사용해야 합니다. 버전 고정 함수가 있는 앱은 Marketplace 호환 대상이 아닙니다.

사용자 지정 Workshop 위젯도 앱과 유사한 방식으로 배포하지만 위젯 집합의 제품 패키징 계약을 따릅니다.

소스만 전달하는 템플릿

소스 저장소는 일반 코드 저장소처럼 패키징합니다. 앱의 빌드 자산과 달리 소스 안의 Ontology RID나 Redirect URL은 자동 매핑하지 않습니다. 앱과 소스를 함께 설치했더라도 소스 파일에는 원본 환경 값이 남을 수 있습니다.

source code templating은 실험적 기능입니다. 모든 이중 중괄호를 변수로 해석하므로 JSX의 style={{color: 'red'}} 같은 코드도 잘못 치환할 수 있습니다. 활성화 전에 코드의 이중 중괄호 사용을 확인합니다.

적합한 용도는 사전 구성 OSDK로 교육 프로젝트 시작, 사용자 예제 배포, 공통 UI 표준 또는 공통 온톨로지 리소스를 사용하는 React 템플릿입니다.

  1. 설치 시 바꿀 값에 {{my_variable}} 형식을 사용합니다.
  2. DevOps에서 저장소를 추가하고 설정 메뉴의 source code templating을 켭니다.

  1. 사용자 지정 매개변수는 설치자가 입력하고 예약 매개변수는 자동으로 치환합니다.
  2. Bootstrap 설치를 선택하면 새 저장소와 연결 Developer Console 앱을 생성합니다.

치환 전 handlebars는 타입 검사에서 실패할 수 있으므로 이 템플릿 코드를 CI 성공 뒤 만드는 웹 자산과 함께 패키징할 수 없습니다.

예약 매개변수

변수값의 역할사용하는 파일
{{FOUNDRY_HOSTNAME}}대상 호스트.env, .npmrc, foundry.config.json
{{APPLICATION_CLIENT_ID}}설치한 앱의 OAuth client ID.env
{{APPLICATION_PACKAGE_NAME}}설치 앱 SDK 패키지 이름package.json과 import 코드
{{APPLICATION_RID}}Developer Console 앱 RIDfoundry.config.json
{{REPOSITORY_RID}}설치 코드 저장소 RID.npmrc, settings.sh
{{ONTOLOGY_RID}}대상 온톨로지 RID.env

APPLICATION_PACKAGE_NAME에는 @와 끝의 /sdk를 포함하지 않습니다. 템플릿이 바로 설치되려면 package.json의 OSDK 버전을 latest 또는 0.1.0으로 설정합니다.

엔터티 API 이름 일치

OSDK 코드와 빌드 자산은 객체 및 액션의 API 이름을 직접 참조합니다. Workshop처럼 RID가 설치 시 새 RID로 매핑되는 흐름과 다르므로 원본과 대상에 같은 이름이 필요합니다.

온톨로지 엔터티를 앱과 같은 제품 또는 함께 배포하는 다른 제품의 출력으로 두고 원본 API 이름 유지 옵션을 사용하는 것이 권장됩니다. 충돌이 있으면 다음 전략을 선택합니다.

상황전략
온톨로지와 앱을 함께 패키징전용 이름 공간을 포함한 완전한 API 이름 사용. 온톨로지당 한 번 설치하는 Singleton 조건과 함께 사용
조직 또는 개발 단계 분리다른 공간과 그에 대응하는 온톨로지로 API 이름의 고유성 범위 분리
대상의 다른 객체 모델이 같은 계약을 구현앱을 인터페이스 기준으로 작성
같은 객체인데 이름만 다름허용되는 메타데이터 상태에서 이름을 맞추고 기존 소비자 영향을 함께 검토

예를 들어 원본 medicine과 대상 vaccine이 공통 의미를 가지면 medicine을 인터페이스로 정의하여 배포하고 vaccine이 그 인터페이스를 구현하게 할 수 있습니다.

API 이름 변경은 다른 앱과 함수에 영향을 주며 메타데이터 상태의 experimental 변경 조건을 따라야 합니다. 이미 사용 중인 안정 유형의 이름을 무조건 바꾸는 절차로 처리하지 않습니다. 많은 엔터티 이름을 handlebars로 치환하는 대신 인터페이스 또는 명시적 제품 입력을 사용하는 편이 관리하기 쉽습니다.