Functions 쿼리 함수 API (V2)
Query는 API 이름, 함수 RID와 버전, 매개변수 및 출력 자료형을 가진 쿼리 함수 정의입니다. 메타데이터를 조회하여 실제 입력 형식을 확인한 뒤 실행합니다. 이 API의 엔드포인트는 모두 미리보기 기능으로 preview=true가 필요하며 언제든 변경되거나 제거될 수 있습니다.
조회와 실행 경로
| 목적 | API |
|---|---|
| API 이름으로 정의 조회 | Get Query |
| 함수 RID로 정의 조회 | Get By RID |
| 최대 100개 정의를 RID로 조회 | Get By RID Queries Batch |
| 전역 함수의 결과를 JSON 객체 하나로 수신 | Execute Query |
| 전역 또는 온톨로지 함수의 결과를 SSE로 수신 | Streaming Execute Query |
조회에는 api:functions-read, 실행에는 api:functions-execute OAuth 권한 범위를 사용합니다. 일반 실행은 전역 함수 경로이며, 온톨로지 범위의 일반 실행에는 온톨로지별 쿼리 실행 API를 사용합니다. SSE 실행은 본문의 선택적 ontology로 두 범위를 구분합니다.
Query 메타데이터
parameters는 매개변수 ID를 키로 하는 맵입니다. 각 항목의 dataType과 required를 확인합니다. required는 메타데이터에 반드시 포함되는 불리언이며, 함수 입력에서 해당 매개변수가 필수인지 나타냅니다.
output은 반환 자료형입니다. 복합 구조와 재귀 정의는 QueryDataType을, 실제 JSON 값의 표현은 DataValue를 따릅니다. typeReferences는 이 Query 안에서 이름으로 참조할 자료형 정의를 담으며 온톨로지 값 유형의 RID 및 버전 참조와 구분합니다.
최신 버전 선택
| 경로 | 버전을 생략한 경우 | 사전 릴리스 |
|---|---|---|
| API 이름 조회, 일반 실행, SSE 실행 | 기본 SEMANTIC_VERSION, 가장 높은 의미 버전 | 기본 제외. PUBLISH_TIME의 기본 동작은 포함 |
| RID 조회와 RID 배치 조회 | 최신 버전 | includePrerelease 기본값은 false이며 버전 생략 시 적용 |
API 이름 조회와 실행의 latestVersionResolution=PUBLISH_TIME은 가장 최근에 게시한 버전을 선택합니다. includePrerelease를 명시하여 사전 릴리스 포함 여부를 정할 수 있지만, 이 경로에서는 명시적 version과 함께 사용할 수 없습니다. RID 조회 경로에는 latestVersionResolution 입력이 없습니다.
함수 버전은 major.minor.patch와 선택적인 사전 릴리스 태그를 사용합니다. 실행 시 branch를 생략하면 기본 Foundry 브랜치를 사용합니다. 브랜치와 버전을 함께 지정하면 그 브랜치에 지정한 버전이 있어야 합니다.
결과와 오류 처리
일반 실행은 ExecuteQueryResponse.value를 반환합니다. SSE 실행은 빈 줄로 구분한 이벤트의 data에 JSON 메시지를 담으며 type이 data 또는 error입니다. 비스트리밍 함수는 전체 결과를 이벤트 하나로, 스트리밍 함수는 배치별 이벤트로 보냅니다.
일부 데이터를 받은 뒤 오류 이벤트가 올 수 있습니다. 클라이언트는 HTTP 상태와 이벤트 종류를 모두 확인하고, 오류 이벤트를 받으면 이미 출력된 데이터가 있어도 실행 실패로 처리합니다.
transactionId는 읽기 트랜잭션을 선택하는 실험적 입력입니다. 지원하는 작업 방식에서 실제 트랜잭션 ID를 사용하며, 예시 문자열을 공통 기본값으로 사용하지 않습니다.