入力および出力タイプ

現在、Functionsでサポートされている唯一の言語はTypeScriptです。このリファレンスは、TypeScript Functionsでの入力および出力タイプに関する詳細なドキュメンテーションを提供します。

レジストリに公開するためには、TypeScript Functionはすべての入力パラメーターに明示的な型注釈を持つ必要があり、明確な戻り値の型を指定する必要があります。

Typescript関数内から外部APIを呼び出すことはできません。アクションの一部として外部APIを呼び出すには、webhooksを使用します。

現在、Functionsで利用可能なすべてのサポートされている入力と出力のタイプは以下のとおりです：

スカラータイプ

• boolean
• string
• Integer、Long、Float、Double
  • JavaScriptおよびTypeScriptでは、numberタイプが一つしかありません。しかし、さらなる型の検証と構造を提供するために、上記のエイリアスのみを@foundry/functions-apiからエクスポートしてサポートしています。これらのタイプを入力と出力として使用するためには、これらのタイプをインポートしてください。
• LocalDateおよびTimestampタイプは、時間情報に使用されます。
  • 数値タイプと同様に、JavaScriptはネイティブでDateタイプをサポートしています。しかし、日付とタイムスタンプを区別するために、@foundry/functions-apiからエクスポートされるより具体的なタイプを提供しています。
  • LocalDateはカレンダーの日付を表し、Timestampは時間の瞬間を表します。

オプションのタイプ

入力パラメーターについては、オプションのパラメーターはvarName?: <type>として宣言されます。例えば、オプションの整数パラメーターvalueを持つ関数は、パラメーターとしてvalue?: Integerを持つでしょう。

関数は、<type> | undefinedのタイプを指定することで、オプションの戻り値タイプを宣言することができます。例えば、Integerまたは値を返さない可能性がある関数は、戻り値のタイプとしてInteger | undefinedを持つでしょう。

コレクション

• リストは、ES6 Arraysを使用してサポートされています（例えば、string[]は文字列の値のリストです）
  • ネストしたリストもサポートされています（例えば、Integer[][]は整数値のリストのリストです）
• セットは、ES6 Setsを使用してサポートされています（例えば、Set<string>は文字列の値のセットです）
• マップは、@foundry/functions-apiパッケージのFunctionsMapを使用してサポートされています。FunctionsMap<K, V>表記を使用して宣言できます。ここでKはキータイプ、Vは 値のタイプです。キーはスカラータイプまたはオントロジーオブジェクト（例えば、FunctionsMap<Employee, string>）であることができます。値は任意のサポートされているタイプであることができます。

集計

集計は、オントロジーオブジェクト上でのbucketed aggregationsを取得する際に返されるタイプであり、他のプラットフォームの部分、例えばWorkshopのチャートで使用するためにFunctionsから返されることができます。

2つの集計タイプがサポートされています：

• TwoDimensionalAggregationは、単一のバケットキーを数値（Doubleとして表現）にマップします。例えば、TwoDimensionalAggregation<string>は、各バケットに対する数値をstringバケットキーにマップします。これは特定の職種の従業員の数を表すような集計を表現するために使用できます。
• ThreeDimensionalAggregationは、2つのバケットキーを数値にマップします。例えば、ThreeDimensionalAggregation<string, string>は、stringバケットキーをネストしたバケットの配列にマップします。これらのネストしたバケットはそれぞれ、数値にマップするstringキーを持っています。これは各従業員の職種と自宅オフィスごとの従業員数を表すような集計を表現するために使用できます。

両方の集計タイプは関数から返され、Workshop Chartsなどのプラットフォームの他の部分で使用可能になります。

集計はいくつかのタイプでキー付けすることができます：

• booleanバケットは、trueまたはfalseの値を表します
• stringバケットは、カテゴリ値を表すために使用できます
• IRange（@foundry/functions-apiから）バケットは、バケットキーが値の範囲である集計を表します。これらは、ヒストグラムまたはチャートの日付軸を表すために使用できます。
  • 数値範囲、IntegerとDoubleを含む、は数値上のバケット化された集計を表します
  • 日付と時間の範囲、LocalDateとTimestampを含む、は日付範囲のバケット化された集計を表します

オントロジータイプ：オブジェクトとオブジェクトセット

オントロジーで設定された各オブジェクトタイプは、Functionsコードで使用するためのTypeScriptインターフェースに変換されます。すべての生成されたタイプは@foundry/ontology-apiパッケージからエクスポートされます。詳細は、TypeScriptのオントロジーAPIの詳細なドキュメンテーションをご覧ください。

• オブジェクトタイプが入力タイプとして使用される場合、関数を実行するクライアントは、関数を実行するオブジェクトのobjectRidまたはオブジェクトタイプと主キーを渡す必要があります
• オブジェクトタイプが出力タイプとして使用される場合、オブジェクトのロケーターが返されます（オブジェクトのタイプと主キー）

オブジェクトのコレクションを関数に入力および出力する方法は2つあります：具体的なオブジェクトのコレクション（配列やセットなど）またはオブジェクトセット。

• 配列やセットのオブジェクトを関数に渡すことで、具体的なオブジェクトのリスト上でロジックを実行することができます。例えば、あなたの関数はemployees: Employee[]またはemployees: Set<Employee>を取ることができ、従業員オブジェクトの配列やセットを受け取ることができます
  • オブジェクト配列パラメーターについては、クライアントはロードするべきオブジェクトのobjectRidsまたはオブジェクトロケーターのリストを渡す必要があります
• @foundry/ontology-apiからエクスポートされるObjectSet<>インターフェースを使用して、オブジェクトセットを関数に渡すことができます。例えば、あなたの関数はemployees: ObjectSet<Employee>を取ることができ、従業員のオブジェクトセットを受け取ることができます。オブジェクトセットはフィルタリング、検索、集計操作を可能にします。オブジェクトセットAPIについて詳しくはこちら。
  • オブジェクトセットパラメーターについては、クライアントは保存されたオブジェクトセットを参照するobjectSetRidを渡す必要があります。オブジェクトセットサービスは、一時的な時間でオブジェクトセットを保存することを許可し、関数のパラメーターとして使用するための短期間のオブジェクトセットを作成することを可能にします

プリンシパル、ユーザー、およびグループ

プリンシパルは、Foundryユーザーアカウントまたはグループを表します。これらのタイプは、関数に渡され、ユーザーまたはグループに関連する情報、例えばグループの名前やユーザーの名前やメールアドレスにアクセスすることを許可します。すべてのプリンシパルタイプは@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をパラメーターとして関数に渡すだけでなく、@foundry/functions-apiからエクスポートされるUsersオブジェクトを使用して、UsersまたはGroupsをアドホックに取得することができます

• getUserByIdAsyncメソッドは、userIdをstringとして取り、Promise<User>を返します
• getGroupByIdAsyncメソッドは、groupIdをstringとして取り、Promise<Group>を返します

通知

通知タイプは関数から返され、プラットフォームで送信するべき通知を柔軟に設定することができます。例えば、Userやオブジェクトタイプなどのパラメーターを取り、設定されたメッセージを持つ通知を返す関数を作成することができます。

• Notificationは2つのフィールドから構成されます：ShortNotificationとEmailNotificationContent。
• ShortNotificationは通知の要約版を表し、Foundryプラットフォーム内で表示されます。短いheading、content、およびLinkのコレクションを含みます。
• EmailNotificationContentは通知のリッチバージョンを表し、外部のメール経由で送信することができます。subject、ヘッドレスHTMLからなるbody、およびLinkのコレクションを含みます。
• Linkはユーザー向けのlabelとlinkTargetを持っています。LinkTargetはURL、OntologyObject、またはFoundry内の任意のリソースのridであることができます。

Notifications APIの使用方法の例については、how-to guideを参照してください。

カスタムタイプ

また、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
import { Function, LocalDate } from "@foundry/functions-api";
import { Employee } from "@foundry/ontology-api";

interface EmployeeGraph {
    value: Employee; // 値としての社員情報
    connections: EmployeeGraph[]; // その社員との関連性を持つ他の社員情報
}

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 Promise は、関数から返され、関数が非同期でデータを読み込むワークフローを可能にします。実行時に、関数エグゼキュータは、Promise が解決されるのを待ってから、クライアントに値を返します。
  • 関数リポジトリへの公開のために Promise タイプが無視されることに注意してください。そのため、Promise<Integer> を返す関数は、関数リポジトリに単に Integer を返すものとして表示されます。

パラメーターオプション

関数パラメーターのデータ型を宣言することに加えて、パラメーターの取り扱いに関していくつかのオプションがあります。

オプションのパラメーターとデフォルト値

TypeScript 関数は、オプションのパラメーターとデフォルト値を持つパラメーターに対応しています。関数パラメーターがオプションの場合、関数リポジトリにそのように公開され、クライアントがそのパラメーターを渡さずに関数を実行できるようになります。これは、特定のユースケースで上書きできる簡単なデフォルトを関数に提供するのに役立ちます。

以下は、オプションのパラメーターを持つ関数の例です：

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リポジトリに公開されます。これにより、ユーザーは機能の説明に基づいて機能を検索でき、Functionの各入力パラメーターが意味する内容についてさらに詳しく説明できます。

以下は、リポジトリに公開されるドキュメントが付いた機能の例です：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
/**
 * 与えられた2つの映画に対して、類似性スコアを計算します。ここで、0は全くの無関連性を、
 * 1は完全な類似性を表します。
 * 
 * @param movie1 比較する最初の映画
 * @param movie2 比較する二番目の映画
 * @param weight 類似性アルゴリズムに使用する閾値
 */
@Function()
public computeSimilarityScore(movie1: Movie, movie2: Movie, weight: Double = 0.75): Double {

}