입력 및 출력 유형

현재 Functions에서 지원하는 언어는 TypeScript만 있습니다. 이 참조서는 TypeScript Functions의 입력 및 출력 유형에 대한 상세 문서를 제공합니다.

등록소에 게시되기 위해서는 TypeScript Function에 모든 입력 파라미터에 대해 명시적인 유형 주석이 있어야 하며, 명시적인 반환 유형을 지정해야 합니다.

Typescript function 내에서 외부 API를 호출하는 것은 지원되지 않습니다. 액션의 일부로 외부 API를 호출하려면 웹훅을 사용하세요.

현재 Functions에서 지원하는 모든 입력 및 출력 유형은 다음과 같습니다:

스칼라 유형

• boolean
• string
• Integer, Long, Float, 그리고 Double
  • JavaScript와 TypeScript에서는 number 유형만 있습니다. 그러나 더 많은 유형 유효성 검사 및 구조를 제공하기 위해, @foundry/functions-api에서 내보낸 위의 별칭만 지원합니다. 이러한 유형을 Function 정의의 입력 및 출력으로 사용하려면 이러한 유형을 가져와야 합니다.
• LocalDate 및 Timestamp 유형은 시간 정보를 위해 사용됩니다.
  • 숫자 유형과 마찬가지로 JavaScript는 기본적으로 Date 유형을 지원합니다. 그러나 날짜와 타임스탬프를 구분하기 위해, @foundry/functions-api에서 내보낸 보다 구체적인 유형을 제공합니다.
  • LocalDate는 달력 날짜를 나타내며, Timestamp는 시간의 순간을 나타냅니다.

선택적 유형

입력 파라미터의 경우, 선택적 파라미터는 varName?: <type>으로 선언됩니다. 예를 들어, 선택적 정수 파라미터인 value를 가진 Function은 파라미터 value?: Integer를 가질 것입니다.

Functions는 <type> | undefined 유형을 지정하여 선택적 반환 유형을 선언할 수 있습니다. 예를 들어, Integer 또는 값을 반환하지 않을 수 있는 Function은 Integer | undefined의 반환 유형을 가질 것입니다.

컬렉션

• 목록은 ES6 배열을 사용하여 지원됩니다(예: string[]은 문자열 값의 목록입니다)
  • 중첩 목록이 지원됩니다(예: Integer[][]은 정수 값의 목록의 목록입니다)
• 집합은 ES6 집합을 사용하여 지원됩니다(예: Set<string>은 문자열 값의 집합입니다)
• 맵은 @foundry/functions-api 패키지의 FunctionsMap을 사용하여 지원됩니다. 이는 FunctionsMap<K, V> 표기법을 사용하여 선언될 수 있으며, 여기서 K는 키 유형이고 V는 값 유형입니다. 키는 스칼라 유형 또는 온톨로지 오브젝트(예: FunctionsMap<Employee, string>)일 수 있습니다. 값은 지원되는 모든 유형이 될 수 있습니다.

집계

집계는 온톨로지 오브젝트에 대한 버킷화된 집계를 검색할 때 반환되는 유형이며, Workshop의 차트 등 플랫폼의 다른 부분에서 사용하기 위해 Functions에서 반환될 수 있습니다.

지원되는 집계 유형은 두 가지입니다:

• TwoDimensionalAggregation은 단일 버킷 키를 숫자 값(즉, Double로 표현됨)으로 매핑합니다. 예를 들어, TwoDimensionalAggregation<string>은 string 버킷 키를 각 버킷에 대한 숫자 값으로 매핑합니다. 이것은 특정 직무 제목을 가진 직원 수와 같은 집계를 나타내는 데 사용될 수 있습니다.
• ThreeDimensionalAggregation은 두 개의 버킷 키를 숫자 값으로 매핑합니다. 예를 들어, ThreeDimensionalAggregation<string, string>은 string 버킷 키를 중첩 버킷의 배열로 매핑합니다. 이 중첩 버킷 각각은 string 키를 숫자 값에 매핑합니다. 이것은 각 직원의 직무 제목과 본사 별 직원 수와 같은 집계를 나타내는 데 사용될 수 있습니다.

두 집계 유형 모두 Function에서 반환될 수 있으며, Workshop 차트에서 특히 플랫폼의 다른 부분에서 사용 가능합니다.

집계는 여러 유형으로 키 지정할 수 있습니다:

• boolean 버킷은 true 또는 false인 값을 나타냅니다
• string 버킷은 범주형 값을 나타내는 데 사용할 수 있습니다
• IRange(@foundry/functions-api에서) 버킷은 버킷 키가 값의 범위인 집계를 나타냅니다. 이것은 차트의 히스토그램 또는 날짜 축을 나타내는 데 사용될 수 있습니다.
  • 숫자 범위, Integer 및 Double을 포함하여, 숫자 값에 대한 버킷화된 집계를 나타냅니다
  • 날짜 및 시간 범위, LocalDate 및 Timestamp을 포함하여, 날짜 범위에 대한 버킷화된 집계를 나타냅니다

온톨로지 유형: 오브젝트와 오브젝트셋

온톨로지에서 구성한 각 오브젝트 유형은 Functions 코드에서 사용할 수 있는 TypeScript 인터페이스로 변환됩니다. 모든 생성된 유형은 @foundry/ontology-api 패키지에서 내보냅니다. TypeScript 온톨로지 API에 대한 상세 문서를 참조하세요.

• 오브젝트 유형이 입력 유형으로 사용될 때, Function을 실행하는 클라이언트는 Function을 실행하려는 오브젝트의 objectRid 또는 오브젝트 유형 및 기본 키를 전달해야 합니다
• 오브젝트 유형이 출력 유형으로 사용될 때, 오브젝트에 대한 로케이터가 반환됩니다(오브젝트 유형 및 오브젝트의 기본 키)

오브젝트의 컬렉션을 Function으로 전달하고 전달받는 방법은 두 가지입니다: 배열 및 집합과 같은 오브젝트의 구체적인 컬렉션, 또는 오브젝트셋.

• 오브젝트 배열 또는 집합을 Function으로 전달하면 구체적인 오브젝트 목록에 대해 로직을 실행할 수 있습니다. 예를 들어, Function은 employees: Employee[] 또는 employees: Set<Employee>를 사용하여 직원 오브젝트의 배열 또는 집합을 받을 수 있습니다
  • 오브젝트 배열 파라미터의 경우, 클라이언트는 로드해야 할 오브젝트의 objectRids 또는 오브젝트 로케이터 목록을 전달해야 합니다
• @foundry/ontology-api에서 내보낸 ObjectSet<> 인터페이스를 사용하면 오브젝트셋을 Function으로 전달할 수 있습니다. 예를 들어, Function은 employees: ObjectSet<Employee>를 사용하여 직원의 오브젝트셋을 받을 수 있습니다. 오브젝트셋은 필터링, 검색 주변, 및 집계 작업을 가능하게 합니다. 오브젝트셋 API에 대해 더 알아보기.
  • 오브젝트셋 파라미터의 경우, 클라이언트는 저장된 오브젝트셋을 참조하는 objectSetRid를 전달해야 합니다. 오브젝트셋 서비스는 임시로 저장된 오브젝트셋을 허용하여, Function 파라미터로 사용하기 위해 짧은 기간 동안 오브젝트셋을 생성할 수 있습니다

주요 사용자, 사용자, 그룹

주요 사용자는 Foundry 사용자 계정 또는 그룹을 나타냅니다. 이러한 유형은 사용자 또는 그룹과 연결된 정보에 액세스할 수 있도록 Function으로 전달될 수 있습니다. 예를 들어 그룹의 이름이나 사용자의 이름 또는 이메일 주소와 같은 정보입니다. 모든 주요 사용자 유형은 @foundry/functions-api 패키지에서 내보냅니다.

• User는 항상 사용자 이름을 가지며, firstName, lastName, 또는 email을 가질 수 있습니다. 또한 Principal와 연관된 모든 필드를 포함합니다.
• Group은 이름을 가집니다. 또한 Principal와 연관된 모든 필드를 포함합니다.
• Principal은 User 또는 Group일 수 있습니다. 주어진 Principal이 User인지 Group인지 확인하려면 type 필드를 검사할 수 있습니다. User와 Group 특정 필드 외에도 Principal에는 id, realm, 그리고 attributes의 사전이 있습니다.

Foundry 사용자 검색

User, Group, 또는 Principal을 파라미터로 Function에 전달하는 것 외에도, @foundry/functions-api에서 내보낸 Users 오브젝트를 사용하여 사용자 또는 그룹을 ad hoc으로 검색할 수 있습니다

• getUserByIdAsync 메소드는 string 형태의 사용자 ID를 받아 Promise<User>를 반환합니다
• getGroupByIdAsync 메소드는 string 형태의 그룹 ID를 받아 Promise<Group>을 반환합니다

알림

알림 유형은 플랫폼에서 보내야 하는 알림을 유연하게 설정할 수 있도록 Function에서 반환될 수 있습니다. 예를 들어, User 및 오브젝트 유형과 같은 파라미터를 받아 설정된 메시지로 알림을 반환하는 Function을 작성할 수 있습니다.

• Notification은 두 개의 필드로 구성됩니다: ShortNotification과 EmailNotificationContent.
• ShortNotification은 알림의 요약 버전을 나타내며, Foundry 플랫폼 내에서 표시됩니다. 짧은 heading, content, 그리고 Link의 컬렉션을 포함합니다.
• EmailNotificationContent은 외부 이메일을 통해 보낼 수 있는 알림의 풍부한 버전을 나타냅니다. subject, body(headless HTML로 구성), 그리고 Link의 컬렉션을 포함합니다.
• Link는 사용자가 보는 레이블과 linkTarget을 가집니다. LinkTarget은 URL, OntologyObject, 또는 Foundry 내의 모든 리소스의 rid일 수 있습니다.

알림 API의 사용 방법에 대한 예제는 how-to 가이드를 참조하세요.

커스텀 유형

또한, Functions에서 사용할 커스텀 입력 및 출력 유형을 정의할 수도 있습니다. 커스텀 유형은 TypeScript 인터페이스로 정의되거나, 인라인 익명 유형으로 정의될 수 있습니다.

• 커스텀 유형의 필드는 위에서 문서화된 다른 유형, 또는 다른 커스텀 유형, 또는 자기 참조할 수 있습니다.
• 선택적 필드는 ? 선택적 토큰을 통해 지원되거나, 필드의 유형이 undefined와의 유니온입니다.

커스텀 유형의 예시:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { Function, LocalDate } from "@foundry/functions-api";
import { Employee } from "@foundry/ontology-api";

// EmployeeGraph는 Employee 객체와 그 연결을 나타내는 인터페이스입니다.
interface EmployeeGraph {
    value: Employee; // Employee 객체
    connections: EmployeeGraph[]; // 연결된 다른 EmployeeGraph
}

// EmployeeFilter는 직원을 필터링하는 데 사용되는 인터페이스입니다.
interface EmployeeFilter {
    maxStartDate?: LocalDate; // 시작 날짜의 최대 값. '?' 표시를 사용하여 옵션으로 설정
    role: string | undefined; // 직무. 'undefined'와의 합집합을 사용하여 옵션으로 설정
}

// 이 함수는 이름이 지정된 사용자 정의 타입을 입력으로 받아 이름이 지정된 사용자 정의 타입을 출력합니다.
@Function()
public myEmployeeSearchAround(root: Employee, filter: EmployeeFilter): EmployeeGraph {
    ...
}

// 이 함수는 익명의 사용자 정의 타입을 출력합니다.
@Function()
public getAverageAndMedianAge(employees: Employee[]): { average: Double, median: Integer } {
    ...
}

기타 유형

• ES6 Promises는 Function에서 반환될 수 있으며, Function이 데이터를 비동기적으로 로드하는 워크플로를 가능하게 합니다. 런타임에서, Function Executor는 클라이언트에게 값을 반환하기 전에 Promise가 해결될 때까지 기다립니다.
  • Promise 유형은 Function Registry에 게시하기 위해 무시되므로, Promise<Integer>를 반환하는 Function은 단순히 Integer를 반환하는 것으로 Function Registry에 표시됩니다.

파라미터 옵션

Function 파라미터의 데이터 유형을 선언하는 것 외에도, 파라미터가 처리되어야 하는 몇 가지 다른 옵션들이 있습니다.

선택적 파라미터와 기본값

TypeScript Functions는 선택적 파라미터와 기본값이 있는 파라미터를 지원합니다. 만약 Function 파라미터가 선택적인 경우, 그것은 Function Registry에 그대로 게시되어, 클라이언트가 그 파라미터를 전달하지 않고도 Function을 실행할 수 있게 합니다. 이것은 특정 유즈케이스에 대해 재정의할 수 있는 간단한 기본값을 제공하는데 유용할 수 있습니다.

다음은 선택적 파라미터가 있는 예제 Function입니다:

Copied!
1
2
3
4
5
6
7
8
9
10
@Edits(Ticket)
@OntologyEditFunction()
public updateDueDate(ticket: Ticket, dueDate?: LocalDate): void {
    if (dueDate) {
        ticket.dueDate = dueDate;
    } else {
        // 기본적으로, 마감 날짜를 다음 주로 설정합니다.
        ticket.dueDate = LocalDate.now().plusDays(7);
    }
}

다음은 기본값이 있는 예제 Function입니다:

Copied!
1
2
3
4
5
@Function()
// 위험 요소 계산 함수
public computeRiskFactor(customer: Customer, weight: Double = 0.75): Double {
    // ...
}

weight의 값은 클라이언트가 특정 값을 전달하지 않는 한 기본적으로 0.75로 설정됩니다.

관련 문서

Function 정의에 JSDoc 명세에 따른 문서가 포함되어 있는 경우, 이 문서는 발견되어 Function Registry에 게시됩니다. 이를 통해 사용자는 설명에 따라 Function을 검색할 수 있으며, Function의 각 입력 파라미터가 무엇을 의미하는지에 대한 추가적인 정보를 제공하는데 사용될 수 있습니다.

다음은 문서가 Registry에 게시되는 함수의 예입니다:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
/**
 * 두 영화에 대한 유사도 점수를 계산합니다. 여기서 0은 전혀 유사하지 않음을 나타내며 
 * 1은 완벽하게 유사함을 나타냅니다.
 * 
 * @param movie1 비교할 첫 번째 영화
 * @param movie2 비교할 두 번째 영화
 * @param weight 유사도 알고리즘에 사용할 임계값
 */
@Function()
public computeSimilarityScore(movie1: Movie, movie2: Movie, weight: Double = 0.75): Double {

}