サービスビルダーリファレンスガイド

イントロダクション

サービスは、アプリケーションの特定の機能的側面に関連する動作をカプセル化します。サービスは、その動作をインターフェースを介して公開します。インターフェースは、サービスの利用者が利用できる手続きやイベントタイプのリストで構成されています。サービスは、 Vantiqカタログ これにより、インターフェースにリモートからアクセスできるようになります。

この章では、サービスビルダーを使用してVantiqサービスを定義する方法について説明します。サービスビルダーは、サービスの定義を3つの主要なカテゴリ（それぞれにタブがあります）に分類します。 インタフェース, 製品の導入, テスト これについては次のセクションで説明します。

サービスを定義する方法の基本を学んだ後、より高度なトピックについて見ていきます。 サービス状態管理 そして作成 GenAIエージェント.

関連文書

最初のサービスを構築する手順については、 入門チュートリアル入門チュートリアルを完了したら、 入門チュートリアルのテスト. また、以下についても知ることができます サービス状態管理 と建物 GenAIエージェント.

インタフェース

サービスインターフェースは、サービスの外部に向けた動作を記述します。その目的は、 何 サービスはそうではない の それは（サービスのドメインである） 実装）。サービスのインターフェースは、インバウンドとアウトバウンドで構成される。 イベントの種類サービスの非同期動作を記述する。 手順、同期動作を記述します。

サービスのインターフェースを理解することは、実装前にサービスの設計を練るのに役立ちます。サービスの要件を理解することは、インターフェースを定義するための最初のステップだからです。また、このサービスを自身のプロジェクトに統合する必要がある他のVantiqユーザーにとっても役立ちます。例えば、サービスのインターフェースは、 カタログ 再利用のために。

サービスビルダーは、サービスインターフェースが実装の定義に合わせて構築される、より「アドホック」な開発スタイルをサポートしています。そのため、新しいパブリックイベント型やプロシージャがサービスビルダーで定義されるたびに、 実装 タブをクリックすると、ビルダーは自動的にインターフェースを更新してそれを含めます。

イベントの種類

サービスイベントタイプは、所有するサービスによるイベントの生成と消費を記述するために使用されます。これにより、サービスによってカプセル化された機能に対するイベント駆動型のインタラクションがコンシューマーに提供されます。これにより、サービスをより大きなイベント駆動型アーキテクチャ (EDA) の一部として活用することがより自然になります。インターフェースタブで定義されるすべてのイベントタイプは「パブリック」であり、サービスのインターフェースの一部です。イベントタイプは、イベントが流れる「方向」に基づいて2つのカテゴリに分類されます。

本国行きの

インバウンドイベントタイプは、コンシューマからサービスに処理のために流れるイベントを表します。サービスコンシューマは、VAILまたは PUBLISH ステートメント または サービスに発行 ビジュアルイベントハンドラ（通常は別のサービスの）内のタスク。以下のプロパティがあります。

• 名前 – イベントタイプの名前。有効な識別子であり、特定のサービス内で一意である必要があります。
• 詳細説明  – イベント タイプの説明。
• 配送モード – 受信したイベントが可能な場合「確実に」処理されるかどうかを示します（ 信頼できるメッセージング ガイド 詳細については、こちらをご覧ください。可能な値は次のとおりです。
  • 最大1回 – イベントは信頼できず、実行時エラーのために処理されない可能性があります。
  • 少なくとも一度 – イベントはサービスによって確実に処理されます。イベントの送信者が信頼できない場合、サービスがイベントを受信する前に障害が発生すると、イベントが失われる可能性があることに注意してください。
• イベントスキーマ – への参照 タイプ このタイプのイベントに関連付けられたデータの構造を記述します。

サービスビルダーは、開発を支援するために、受信イベントタイプを直接「公開」する方法を提供しています。受信イベントタイプの例（チュートリアルから抜粋）を以下に示します。 SpeedEvent サービスによる処理のために、エンジンの現在の速度に関するデータを伝送します。

外国行きの

アウトバウンドイベントタイプは、サービスからサービスコンシューマ（複数可）へ（匿名で）流れるイベントを表します。サービスコンシューマは、これらのイベントを WHEN 句 ルールのトリガー条件として、または ビジュアルイベントハンドラー次のような特性があります。

• 名前 – イベントタイプの名前。有効な識別子であり、特定のサービス内で一意である必要があります。
• 詳細説明  – イベント タイプの説明。
• 配送モード – イベントが確実に送信されるかどうかを示します（ 信頼できるメッセージング ガイド 詳細については、こちらをご覧ください。可能な値は次のとおりです。
  • 最大1回 – イベントは信頼できず、実行時エラーのために配信されない可能性があります。
  • 少なくとも一度 – イベントは確実に送信され、サービス コンシューマーは適切なタイミングでイベントの受信を確認することが期待されます。

サービスビルダーは、開発を支援するために、アウトバウンドイベントタイプ経由で送信されたイベントを表示する方法を提供します。アウトバウンドイベントタイプの例（チュートリアルから抜粋）を以下に示します。 EngineMalfunction これは、サービスが特定の危険なエンジン状態を検出したときに生成されます。イベントデータには、検出された状況の詳細が含まれます。

手順

サービスの手続きは、外部に対して同期的な動作を表します。 インタフェース タブでは、各プロシージャのシグネチャの定義に焦点が当てられています。これは、プロシージャの実行に必要なパラメータを記述します。 手順 そして、プロシージャの戻り値の型です。このシグネチャは、プロシージャの実装のスケルトンを生成するために使用されます。開発が進むにつれて、サービスビルダーはインターフェースのシグネチャが実装で表現されたものと一致することを確認します。

プロシージャ シグネチャには次のプロパティがあります。

• name – プロシージャの名前。有効な識別子であり、特定のサービスごとに一意である必要があります。
• description – 手順の説明
• parameters – パラメータ記述子の配列。各パラメータ記述子は以下を定義できます。
  • 名: パラメータ名。プロシージャ内で一意かつ有効な識別子でなければなりません。
  • 説明: パラメータの説明
  • type: 提供された値のスキーマを記述するタイプ（組み込みまたはユーザー定義）
  • マルチ: 渡される値が配列であることを宣言するブール値
  • : パラメータが必須であり、呼び出し側は必ず値を指定する必要があることを宣言します（ただし、その値は null でも構いません）。
  • デフォルト: パラメータに値が指定されていない場合は、指定された値を使用することを宣言します。
• returnType – このプロシージャによって返される値のスキーマを記述するタイプ（組み込みまたはユーザー定義）

オプションではあるが、すべてのタイプを宣言することを強く推奨する。 パラメータ と 戻り型存在する場合、システムはパラメータに指定された値が宣言された型の有効な値であるかどうかを検証し、サポートされているすべての処理を自動的に実行します。 型変換戻り値の型が指定されている場合、システムはその型を使用して、プロシージャによって生成された値を検証および変換します。VAILは動的型付けされているため、これらの検証/変換は実行時に行われます。さらに、Vantiqシステムは要求された操作が実行可能であることを確認し、実行できない場合はエラーを生成します（「ダック」タイピングとも呼ばれます）。

VAILにおける手順の定義の詳細については、 VAIL リファレンス ガイド.

製品の導入

サービスの実装は（詳細に）正確に記述されています の サービスは公開インターフェースを提供します。実装には、インターフェースに含まれない内部の詳細（「プライベート」アーティファクトと呼ばれます）も含まれます。インターフェースと同様に、これらは定義される機能の「タイプ」に基づいて、イベントハンドラ、プロシージャ、GenAIプロシージャに分類されます。

イベントハンドラー

パブリックイベントハンドラー

各 受信イベントタイプ サービスのインターフェースにおけるイベントハンドラは、パブリックな「イベントハンドラ」の定義によって実装されます。これらは ビジュアルイベントハンドラー （別名アプリ）または ルール （別名VAILイベントハンドラー）。以下はビジュアルイベントハンドラーの例です。

デフォルトでは、各イベントハンドラは単一の受信イベントタイプからイベントを受け取ります（上記参照）。ただし、ビジュアルイベントハンドラを定義する場合は、追加のイベントタイプを追加できます。 イベントストリーム タスクはそれぞれ異なる受信イベントタイプにバインドされています。これにより、 ジョイン の三脚と マージ ビジュアルイベントハンドラー内で、単一のハンドラーで複数のイベントタイプを処理できます。VAILイベントハンドラーは、単一のイベントタイプの実装に制限されています。

イベントハンドラはサービスの実装の一部とみなされるため、サービスのプライベートプロシージャへのアクセスが許可されます。単一のパーティションのプライベートプロシージャを呼び出す場合、イベントハンドラのコードは、以下に示すように、パーティションキーを明示的に指定する必要があります。 分割実行.

これは、ことは注目に値します ビジュアル イベント ハンドラ イベントハンドラの実装に基づいて、サービス定義が自動的に拡張されます。特に、ビジュアルイベントハンドラは、必要に応じて、送信イベントタイプ、状態管理手順、および状態タイプ定義を生成します。ビジュアルイベントハンドラとサービスとの連携の詳細については、 ビジュアルイベントハンドラービルダーガイド.

プライベートイベントハンドラー

サービスのインターフェースで定義されるパブリックな受信イベント型に加えて、サービスは1つ以上のプライベートなイベントハンドラを定義することもできます。これにより、サービスはイベント処理をプライベートな実装の一部として利用できるようになります。名前が示すように、プライベートなイベントハンドラの受信イベント型は、サービス自体にのみ表示されます。それ以外の場合は、他のイベント型と同様に使用できます。

ソースおよびサービスイベントハンドラー

ソースおよびサービスイベントハンドラは、サービスがソースから受信したイベントを処理できるようにします。 ソース or サービスこれらはサービスの実装の一部であり、サービス利用者からは見えません。ソースイベントハンドラーまたはサービスイベントハンドラーの一般的なパターンは次のとおりです。

• 外部イベントの取り込み。
• 何らかの処理または変換を実行する。
• 結果を他のサービスがトリガーするためのアウトバウンドイベントタイプとして公開する

ソースおよびサービス イベント ハンドラーを使用すると、サービスはソースまたはその他の外部イベントのラッパーとして機能できます。

イベントルーティング

上のセクションで述べたように、 ソースおよびサービスイベントハンドラー しなければなりません 実装するイベントタイプによってトリガーされることはありません。ただし、多くの場合、あるサービスのアウトバウンドイベントタイプが別のサービスのインバウンドイベントタイプの処理をトリガーすることは有用です。 サービスルート、定義 デザインモデラーは、アウトバウンドイベントタイプからインバウンドイベントタイプへの経路です。2つのイベントタイプ間にルートが存在する場合、システムは、パブリッシュ側のアウトバウンドイベントタイプからインジェスト側のインバウンドイベントタイプへイベントを自動的に送信します。ルートはデザインモデラーで動的に定義されるため、どちらのサービスも他方の存在を認識する必要はありません。これは、ルートの追加、更新、削除は、基盤となるサービス定義を更新することなく実行できることも意味します。これは、Vantiq経由でインストールされたサービスを構成する際に特に便利です。 カタログ.

手順

手順は、 命令的サービスとのやりとりにはリクエスト/レスポンス方式を採用しています。 手順署名 サービスのインターフェースで定義されているものには、関連付けられている 公共 実装手順。また、サービスでは任意の数の プライベート 独自の内部使用のための手順。

ベイルの手続き

サービス手順を実装する1つの方法は、 べイル 動作を記述する。これは非常に汎用的なアプローチであり、あらゆるアルゴリズムを効果的に実装する手順を定義するために使用できます。 サービス手順 サービス手順を定義するための正確なVAIL構文のドキュメント。ここでは、パブリックVAIL手順の定義例を示します。

GenAIの手順

サービス手順を実装するもう一つの方法は、GenAI手順を作成することです。GenAI手順は、 GenAI ビルダー GenAIフローを記述します。GenAIフローは、大規模言語モデル（LLM）と セマンティックインデックス 様々なデータ分析タスクを実行します。ここでは、公開されているGenAIプロシージャが定義されています。

GenAI プロシージャは常に 2 つのパラメータで定義されます。

• 入力（Any) – GenAI プロシージャによって処理されるデータ。
• 設定（Object) – GenAI プロシージャを実行するときに適用されるランタイム構成値。

GenAIプロシージャの戻り値の型はデフォルトで Anyただし、任意の有効なタイプに設定できます。

サービステスト

サービステストは通常​​の テスト 機能。ただし、サービステストは、個々のサービスやサービス内の個々のユニットの機能を正確に特定することに特化しています。

ユニットテスト

サービスユニットテストは、サービスイベントハンドラの単一のサービスプロシージャの機能をテストします。サービスユニットテストでは、テスト対象を指定します。 リソースを追加する。 サービスとして（"/services/<serviceName>"）を指定し、 ユニット参照 テスト対象ユニットに基づいて。 ユニット参照 は、テストのプロパティであり、形式は次のとおりです。 {タイプ： 、 名前： } ここで、typeは イベントタイプ or 手続き ユニット名は、テスト対象となるイベントタイプまたはプロシージャの名前です。サービスユニットテストは、プライベートサービスプロシージャをテストするための唯一のメカニズムです。

サービスユニットテストでは、テストへの入力はテスト対象のユニットのみである必要があります。インバウンドイベントタイプの場合、テスト入力はそのインバウンドイベントタイプへのパブリッシュのみであることを意味します。プロシージャの場合、テスト入力はそのプロシージャの実行のみであることを意味します。サービスユニットテストでは、テスト出力はアウトバウンドサービスイベントタイプ、サービスプロシージャ、または想定されるエラーのみである必要があります。サービスプロシージャは、特定の状態プロパティの値を検証するために使用できます。プロシージャの出力は、他のすべての出力が受信された後、またはテストのタイムアウトが経過した後に、テストの最後に実行されます。

ユニットテストの詳細については、 テストガイド.

結合テスト

サービス統合テストではテストを指定します リソースを追加する。 サービスとして（"/services/<serviceName>"サービス統合テストは、サービス全体の機能をテストします。サービス統合テストでは、プロジェクトではなく、サービスをテストリソースとして定義します。実行時に、サービス統合テストは、サービスとその実装リソースのみを含むプロジェクトを生成します。このプロジェクトは、プロジェクトの他の部分から分離してテストできるように、テスト名前空間にデプロイされます。

サービス統合テストでは、サービスインターフェースのみを使用してサービスと対話する必要があります。これにより、サービスの利用者がサービスを使用する方法を正確にシミュレートできます。つまり、有効なテスト入力は、受信サービスイベントタイプへのパブリッシュと、公開サービスプロシージャの実行のみとなります。有効なテスト出力は、送信サービスイベントタイプ、サービスプロシージャ、または想定されるエラーでのイベントの予測のみとなります。サービスプロシージャは、特定の状態プロパティの値を検証するために使用できます。プロシージャ出力は、他のすべての出力が受信された後、またはテストのタイムアウトが経過した後に、テストの最後に実行されます。

統合テストの詳細については、 テストガイド.