Connectorを作る
Connectorは、ActQLの中で外部システムと話す唯一の部分です。このページは、一覧にないシステムをつなぎたい人、またはActQLのスキルを使って作業するコーディングエージェントのためのものです。Connectorが何を宣言するか、エンジンがそれぞれの宣言をどう使うか、そして作って試すまでの手順を説明します。リポジトリの中での具体的な作業はリポジトリでのConnectorの作成にあります。
Connectorが宣言するもの
Connectorは、一連の宣言と、入出力を行うコードでできています。エンジンがシステムのAPIを直接見ることはなく、見るのは宣言だけです。
| 宣言 | 何を表すか | エンジンはどう使うか |
|---|---|---|
| SourceView | プログラムが読めるリソース。型付きの列、バージョン、キーを持つ | check が名前と型を検証し、explain が読み取りを計画し、読み取った結果は観測として記録される |
| Capability | そのシステム自身が計算できること（列の選択、絞り込みとその演算子、並べ替え、集計、検索）と、おおよそのコスト | プランナーは宣言されたものだけをプッシュダウンし、それ以外はエンジンで実行する |
| Effect | プログラムが実行できるレコードの書き込み（追加、更新、UPSERT、削除）。リソースごとのMappingとして、キー、書き込める項目とその型、それぞれに必要な権限、プレビューの強さを持つ | ポリシーが操作ごとに判断し、Hostがプレビューを作り、承認し、Connectorを通して送る |
| Command | プログラムが EFFECT COMMAND で実行できる操作（投稿、送信、更新処理の開始、ジョブの起動）。それぞれがバージョン付きの契約で、入力の項目と型、対象となるリソースの種類、権限、プレビューに出る内容、結果の確認方法を持つ | check は conn.operation をちょうど1つの契約に解決し、曖昧なら拒否する。HostはほかのEffectと同じようにプレビューと承認を行う |
| Store | コンテンツ（content_ref）やレコードを書ける場所（オブジェクトストア、ステージ、宣言済みのテーブル）と、保存先が受け取るフィールド、上書きの規則 | EFFECT STORE と CREATE TABLE は、保存先、コンテンツの識別子または件数、上書きの条件とともにプレビューされる |
| 突き合わせ | 応答が失われた操作を、あとから調べる方法 | unknown の結果はこの手順で解決し、再送では解決しない |
| 接続 | 接続に必要な設定項目と認証情報 | Hostが秘密情報を解決し、許可された操作ごとにConnectorへ貸し出す |
Connectorが宣言するのは「できること」です。プログラムが実際に「してよいか」は、Hostのポリシーが毎回判断します。
読み取り元
SourceViewは、システムのリソースをテーブルに対応づけます。名前、型付きの列、NULLを許すかどうか、システムにキーがあればそのキー、そしてリソースのページングのしかたです。キーは、システムが裏付ける主張です。システムが一意性を保証する場合にだけ宣言し、Connector自身が検証しなければならない場合（主キーを強制しないDWH）はMappingにそう書きます。ファイルの内容は別のSourceViewです。resource と version を持つ一覧と、それでJOINして content_ref を返す contents のビューに分け、一覧の列にはしません。Connectorは求めに応じてページを読み、レコードを返します。エンジンはそれをRunの観測として記録し、そのRunの中で二度と読み直しません。読み取りには上限があり、プログラムの件数とバイト数の上限が読み取りごとに適用され、超えそうな読み取りはエラーで止まります。
型は正直に宣言してください。APIが整形済みの文字列で返す列は文字列です。数値にしてよいのは、APIが数値であることを保証している場合だけです。日付と日時は、システムが持つ精度のまま扱います。
Capability
Capabilityは、システムがSourceViewに対して自分で実行できる演算を1つずつ表します。これらの列を選ぶ、この列をこれらの演算子で絞り込む、この列で並べ替える、集計する、といったことと、コストの区分です。プランナーはこれをもとに配置を決め、explain がその結果を表示します。Capabilityは意味を正確に保たなければなりません。システム側の絞り込みの意味がSQLと違う場合（大文字小文字の扱い、NULLの扱い）、Connectorはその絞り込みを宣言しません。
Effect
Effectの宣言は、リソース、操作とその項目、アカウントに必要な権限、そしてプレビューの強さを表します。
full_diff— Connectorが対象の現在の値を読むので、プレビューに変更前と変更後が出る。さらに、読んだ内容（リビジョン、etag、generation、レコードのハッシュ）を書き込みの条件にできる。その間に変わった対象は、項目がfailed（conflict）になる。古いプレビューのまま上書きされることはない。targeted— 対象は分かっていて新しい値も出るが、見せるべき現在の値がない。作成、投稿、送信、アップロードがこれにあたる。
プレビューの強さはこの2つだけです。送る前に対象を正確に特定できないEffectは宣言できません。
システムの制約からキーの一意性を確かめられないConnectorは、プレビューを作る時点で検証します。キーが複数の対象に一致する項目は failed になり、単一の対象への変更として適用されることはありません。
ConnectorはEffectとCommandごとに3つのことを実装します。承認された項目からリクエストを組み立てること、承認された項目ごとにちょうど1回送ること、応答を applied（システムが結果を確認した）、accepted（システムが要求を受け付け、あとで完了させる）、failed のどれかに分類することです。再試行はしません。項目の順序を変えません。完了を自分で決めません。台帳を持つのはHostです。論理的な項目と物理的なリクエストは別のものです。100件の項目を1つの MERGE や1回のバッチ呼び出しで送ってもかまいませんが、各項目は自分の識別子、プレビューの行、結果を持ち続けます。
突き合わせ
どのEffectとCommandにも、応答が失われたときに何が起きたかを知る手段が必要です。良い突き合わせは、リクエストと相関できるシステム自身の記録を使います。送信前にConnectorが記録したジョブや文のid、冪等性キー、リクエストのメタデータに入れたマーカー、この連携とリクエストの時間帯を示す監査や履歴の記録などです。対象を読み返して期待どおりの値があることや、送信後の更新日時は証跡になりません。別の誰かが書いたのかもしれないからです。それ以上の手がないConnectorは結果を unknown のまま残し、Hostはそれを見える状態に置いておきます。リクエストとその識別子は送信前に結び付けてください。リクエストの途中でプロセスが落ちても照会できるようにするためです。
手順
- システムを整理する。 プログラムが読むべきリソースとその列・型・キー、公開するファイル、実行すべき書き込みと操作を挙げます。接続の設定項目と、ローカルのHostに必要な認証情報を決めます。Cloudで承認済みのOAuthアプリが必要なConnectorはメモしておきます。
- SourceViewとCapabilityを宣言する。 まずは列の選択と、APIがもともと対応している絞り込みから始めます。意味がSQLと正確に一致する場合にだけ足します。
- Effect、Command、Storeを宣言する。 キー、入力、プレビューの強さ、権限と、双方向の型の対応を決めます。
- 入出力を実装する。 ページングつきの読み取りとコンテンツの読み取り、EffectとCommandごとの組み立て・送信・分類、突き合わせの照会です。
- フィクスチャを書く。 Connectorは、本物のAPIの応答を記録したものに対して試します。成功した読み取り、ページングのある読み取り、各Effectの成功と失敗、応答の喪失とその突き合わせです。フィクスチャは認証情報なしで動き、mockプロファイルが返すのもこれです。
- Connectorを登録する。 接続から選べるようにし、共通のConnector検査を通します。承認前の送信が0回、承認された項目ごとに送信が1回、再起動後に再送なし、応答が失われたら
unknown、です。
Connectorがしてはいけないこと
- プログラムの入力からURL、メソッド、ヘッダーを決めること。転送先は宣言で固定されていて、プログラムがその外に出ることはできません。
- APIのエラーを、空のレコードやNULLに変えること。
- 自分の操作を完了にしたり、書き込みを自分で再試行したりすること。
- 認証情報を保持すること。解決するのはHostで、操作ごとに貸し出されます。
次に読む
- Connector：ActQLに同梱されるConnectorと、その設定
- リポジトリでのConnectorの作成：コードの置き場所、作者向けのインターフェース、フィクスチャの仕組み
- 仕様：プロトコル：Connectorが実装するCatalog、SourceView、Mapping、Commandの契約
Source: actql/actql/docs/connectors/authoring.md at d904416674e4 · Edit on GitHub