Courier：Gluesyncのパイプラインが、双方向でRESTに対応するように

Courierは、REST APIをGluesyncのソースおよびターゲットとして統合します。Core HubでAPIを一度定義すれば、同じパイプラインを使用して変更を送信したり、レコードを取り込んだりすることができます。

Gluesync 2.3.2.1 では「Courier」が導入されました。これにより、REST API がパイプラインのソースおよびターゲットとして利用可能になります。パイプラインは、キャプチャされたすべての変更を API に配信したり、API からレコードを取得したりすることができ、その際、データベースで既に使用しているのと同じエンティティ、マッピング、チェックポイントを利用できます。Courier は Core Hub の REST エディタであり、HTTP エージェント（courier-agent）は Core Hub に同梱されています。デプロイ作業は一切不要です。メニューから Courier を開き、API の定義を開始してください。

前回のリリースについては、Gluesync 2.3.2: 特定時点での再起動、災害復旧、レイクファイルクエリ、Podman で解説しています。

なぜCourierなのか

どの統合プロジェクトにも、読み取るデータベースがなく、APIしか持たないシステムが1つは存在します。これまで、そのようなシステムにはスクリプトやcronジョブが必要であり、それが動作しなくなった際に誰が責任を負うかについて、長々とした議論が交わされてきました。Courierは、そのAPIをパイプラインの重要な構成要素へと変えます。Web UIで一度定義すれば、すべてのパイプラインで再利用可能になり、他のエージェントと同様に監視やチェックポイントの設定が行えます。

使用場面

・APIへの送信：HTTPターゲットを使用して、データベースから取得したすべてのINSERT、UPDATE、DELETEを、SaaSアプリケーション、社内サービス、またはパートナーのエンドポイントにプッシュします
・HTTP経由でのレコード送信：HTTPソースを使用して、SaaSのWebhook、デバイス、または自社アプリケーションからパイプラインにレコードをプッシュさせ、任意のGluesyncターゲットに配信します
・1行で、より多くのAPIへ：コレクションごとに1つのHTTPターゲットを追加するだけで、同じ行のデータが必要なすべてのAPIに送信されます

機能の説明

HTTP ターゲット：任意の API に変更されます

コレクションとエンドポイント：コレクションには、ベース URL と認証情報（None、Basic、Bearer、またはヘッダーもしくはクエリ文字列内の API キー）が含まれます。そのエンドポイントには、動詞（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）、パステンプレート、ヘッダー、ボディタイプ（NONE、JSON、FORM_URLENCODED）、および型付きバインディング（PATH、QUERY、BODY、HEADER、型はSTRING、NUMBER、またはBOOLEAN）が含まれます。
データベースと同じモデル：パイプラインはコレクションをスキーマとして、エンドポイントをテーブルとして認識します。ソーステーブルをAPIに紐付けることは、データベースに紐付けることと同じです。エンドポイントを選択し、列をマッピングします。「Map to pipeline」は、エンドポイント側からマッピングを構築します
変更ごとに1回の呼び出し：キャプチャされたすべての挿入、更新、削除が1回のHTTP呼び出しになります。各エンドポイントには1つの動詞があり、操作はボディフィールドのoperationおよび{__operation}プレースホルダーで送信されます。スナップショットの行は更新として送信されます
2回送信、1回適用：すべてのリクエストにはIdempotency-Keyが含まれます。これは、ソース位置、テーブル、操作、値、および前のイメージのSHA-256ハッシュです。リトライや再開の後、Core Hubが変更を再度引き継ぐ際も、この値は変わりません
配信ルールの明確化：2xx以外の応答（3xxを含む）は書き込みの失敗とみなされ、チェックポイントから再試行されます。リダイレクトは決して追従されません。DELETEに対して404または410が返された場合は、配信済みとみなされます。接続には10秒、全体では30秒のタイムアウトが設定されています
フィルタを優先：パイプラインのフィルタは配信前に適用されるため、必要な行のみがAPIに到達します

HTTP ソース：HTTP 経由でのレコード

受信エンドポイント：エージェント自身のリスナー（デフォルトではポート 8090）上で、POST /api-inbound/<basePath>/<path> 宛てに、CREATE、UPDATE、および DELETE
「承認前に永続化」：認証済みの各リクエストは、ディスクキュー上の1つのパイプライン行となり、クライアントが202 Acceptedとそのシーケンス番号を受け取る前にディスクに書き込まれます。パイプラインは、エンドポイントごとに少なくとも1回、順序通りに任意のターゲットへこれを配信します
型付き行：インバウンドの STRING は VARCHAR(255) に、NUMBER は NUMERIC(18,2) に、さらに BOOLEAN にマッピングされます。キーのないエンドポイントには、合成キー _seq が割り当てられます
負荷下でも安定：ボディサイズ、処理中のリクエスト数、キューサイズ、および空きディスク容量の制限を超えた場合、システムは 408、413 または 503 を Retry-After とともに返します。デフォルト値は、ボディあたり1024 KB、処理中のリクエスト数64件、エンドポイントごとのバックログ2048 MB、合計8192 MB、空きディスク容量の1 GBまたは5%です
Observable：http_source_requests_total{endpoint,status} メトリクスは、エンドポイントおよびステータスごとにすべてのリクエストをカウントします

利便性よりもセキュリティを優先

着信トークン：着信には、gluesync.https_agentスコープを持つパーソナルAPIトークンが必要です。このトークンは、マネージャーまたはスーパーアドミンが所有し、コレクションの許可リストおよびブロックリストに登録されている必要があります。ビューアーおよびモニターのトークンは403
デフォルトでTLSを有効化：着信リスナーにはキーストアが必要です。inboundAllowPlainHttpを有効にしない限り、プレーンHTTPはループバックでのみ受け入れられます
シークレットの保護：認証情報およびヘッダー値は保存時に暗号化され、すべての応答においてマスクされます
アウトバウンド保護：GS_COURIER_ALLOW_LOCAL_EGRESS=trueを設定しない限り、アウトバウンド呼び出しはループバック、リンクローカル、クラウドメタデータ、マルチキャスト、NAT64アドレス、およびCore Hub自身のポートには決して到達しません。プライベートなRFC 1918範囲は許可されます

次回予告：HTTP経由のストアドプロシージャ

次期Gluesyncリリースでは、Courierにストアドプロシージャの呼び出し機能が追加されます。新しいEXECUTE操作により、受信HTTPリクエストから、パイプラインのソースまたはターゲットであるSQLエージェントのデータベース上のストアドプロシージャや関数を呼び出すことが可能になります。ビジネスロジックは従来通りデータベース内に保持され、HTTPに対応するクライアントであれば、1回のリクエストでそれを実行できます。

7つのデータベース：PostgreSQL、YugabyteDB、MySQL、MariaDB、SQL Server、Oracle、Db2 LUW
型付きパラメータ：IN、OUT、およびINOUTパラメータは、パス、クエリ文字列、またはJSONボディからバインドされ、すべての値はルーチンで宣言されたSQL型に変換されます
完全な応答：レスポンスには、OUTパラメータの値、最大16個の結果セット、および行数が、JSONまたはXML形式で含まれます
明確なエラー：失敗時は400、409、422、または504
制限付きかつトランザクション対応：呼び出しはデフォルトで30秒後にタイムアウトし（最大300秒まで設定可能）、ルーチンが独自にコミットしない限り単一のトランザクション内で実行されます
同一のセキュリティモデル：呼び出しにはHTTPソースと同じパーソナルAPIトークンが使用され、エンドポイントとして設定されたプロシージャのみが呼び出せます

設定は、Courierの新しい「プロシージャ」タブで行います。すべての呼び出しは、設定されたエンドポイントへの着信HTTPリクエストから開始されます。

開始方法

Core Hub を 2.3.2.1 以降にアップグレードしてください。このバージョンには、HTTP エージェントと Courier モジュールが含まれています。セットアップを自動化するために、ブートストラップツールの courier ブロックが、エージェントの設定前に Courier の定義を作成または更新します
Core Hub メニューから Courier を開き、コレクションを作成します：ベース URL と認証
エンドポイントを追加します：動詞、パステンプレート、ヘッダー、ボディタイプ、およびバインディング。[テストリクエストを送信]を使用して、APIの応答を確認します。各エンドポイントの最新50件の結果が保持されます
データを出力する場合は、HTTP Targetを使用してパイプラインを作成し、エンドポイントをターゲットテーブルとして選択して列をマッピングするか、[パイプラインにマッピング]を使用します。HTTP Targetの設定に従ってください
レコードを取り込む場合は、HTTP Sourceを使用してインバウンドエンドポイントを公開し、HTTPSエージェントスコープのパーソナルAPIトークンを発行して、クライアントをそのエンドポイントに設定します。HTTP Sourceの設定に従ってください

HTTP Sourceは、ベアラー・トークンを送信できる任意のHTTP/1.1クライアントを受け付け、HTTP Targetは、http://またはhttps://を経由して、受信したデータに対して2xxステータスコードを返す任意のHTTP/1.1 APIにアクセスします。HTTP Targetには、一括読み込み、UDF、truncate機能はありません。APIが期待する通り、変更内容を1回の呼び出しごとに1つずつ配信します。変更点の完全なリストは、HTTPエージェントの変更履歴に記載されています。

なぜCourierなのか

使用場面