Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Custom Endpoints 개요

Custom Endpoints는 조직이 사용하는 URL, HTTP 메서드와 요청/응답 형식으로 Foundry 기능을 제공하는 앱입니다. 엔드포인트는 온톨로지 함수 또는 액션을 실행하며 HTTP 입력과 온톨로지 작업 사이의 매핑을 플랫폼에서 관리합니다.

기능은 Beta이며 플랫폼 인스턴스에 따라 사용할 수 없습니다. 접근이 필요하면 Palantir Support에 요청합니다.

표준 API와 사용자 지정 경로

가상의 설문 조회 함수가 form_id와 section_id를 입력받는다고 가정합니다. 표준 Query 실행은 다음 경로와 본문을 사용합니다.

POST /api/v2/ontologies/{ontology}/queries/{queryApiName}/execute
Content-Type: application/json

{"parameters":{"form_id":62536,"section_id":5}}

표준 Execute Query 응답의 value에 함수 반환값이 들어갑니다. 문자열 목록을 반환하는 이 가상 예에서는 다음 형태입니다.

{"value":["Val1","Val2","Val3"]}

Custom Endpoints로는 조직의 URL 규칙에 맞는 경로를 정의하고 경로 매개변수를 같은 함수 입력에 연결할 수 있습니다.

GET /myApi/form/62536/section/5

이 URL은 엔드포인트 집합에 등록한 서브도메인에서 제공합니다. 경로 패턴은 /myApi/form/{form_id}/section/{section_id}이며 필요한 경우 section1, section2, section3처럼 조직에서 정한 필드를 가진 응답 구조를 설계할 수 있습니다. 이는 가상 API 설계 예이며 HTTP 상태 코드와 응답 JSON의 필드는 구분합니다.

적용할 수 있는 상황

기존 기업 시스템의 경로 및 응답 규격을 유지하면서 Foundry를 백엔드로 사용할 수 있습니다. 별도의 외부 미들웨어에서 HTTP 요청을 온톨로지 작업으로 변환하던 구성을 플랫폼의 엔드포인트 정의로 옮길 수 있습니다.

Foundry 데이터와 외부 서비스를 함께 사용하는 함수도 기반 작업으로 연결할 수 있습니다. 외부 서비스와 데이터에 실제로 접근하는 로직 및 권한은 그 함수가 갖춰야 합니다. 엔드포인트를 정의하는 것만으로 다른 시스템의 데이터가 자동 결합되지는 않습니다.

구성 단위와 버전

엔드포인트 정의

엔드포인트 정의는 요청 경로, HTTP 메서드와 입력 매핑을 정합니다. header, query, path와 body의 값을 기반 함수 또는 액션의 매개변수로 전달합니다. 정의 하나는 엔드포인트 집합 하나에 속합니다.

예를 들어 가상 경로 /form/{formId}/section/{sectionId}의 formId를 기반 함수의 form_id 입력에 연결할 수 있습니다. HTTP 경로 이름과 함수의 매개변수 이름이 달라도 매핑으로 대응시킵니다.

엔드포인트 집합

엔드포인트 집합(Endpoint set)은 관련 엔드포인트를 묶는 Compass 자원입니다. 개발자의 보기, 수정, 게시와 배포 권한을 이 자원에서 관리합니다. 생성 시 상위 프로젝트 또는 폴더의 권한을 상속합니다.

Configuration에서 집합에 속한 정의를 편집합니다. 현재 편집 중인 설정과 이미 게시한 릴리스의 설정은 구분해야 합니다.

서브도메인

요청을 받을 서브도메인은 Control Panel의 등록 및 승인 절차를 거칩니다. 엔드포인트 집합마다 그 집합의 생성 및 설정 절차에서 요청하여 집합과 도메인을 연결해야 합니다. Control Panel에서 별도로 만든 독립 서브도메인은 Custom Endpoints에서 지원하지 않습니다.

게시와 릴리스

게시하면 현재 집합의 설정을 캡처한 불변 릴리스를 만들고 의미적 버전을 붙입니다. 설정 상태를 보존하는 점은 Git commit, 버전 이름을 붙이는 점은 Git tag와 비슷합니다. 게시한 릴리스의 내용은 바꿀 수 없지만 릴리스 자체는 삭제할 수 있습니다. 정의를 수정한 뒤에는 새 버전을 게시해야 합니다.

배포와 호출 버전

여러 릴리스를 같은 서브도메인에 동시에 배포할 수 있습니다. 요청의 endpoint-api-version 헤더로 배포 버전을 선택합니다. 헤더를 생략하면 최신 배포 버전을 사용합니다. 최신 편집 상태나 아직 배포하지 않은 최신 게시 버전과는 다릅니다.

beta, stable과 legacy 릴리스를 함께 제공하면서 호출 앱별로 버전을 정할 수 있습니다. 게시 및 배포 절차에서 두 단계를 구분합니다.

구성 순서

  1. 엔드포인트 집합과 서브도메인을 만들고 승인을 요청합니다.
  2. 함수와 액션의 요청 매개변수를 연결합니다.
  3. 릴리스를 게시하고 배포한 뒤 실제 호출 계약을 확인합니다.
  4. Unrestricted OAuth 앱에서 배포 버전을 선택하여 사용합니다.

엔드포인트 정의를 저장하거나 릴리스를 게시한 상태만으로는 외부에 공개되지 않습니다. 승인한 도메인에 릴리스를 배포해야 호출할 수 있습니다.