データソース API

ソースプリセットを一覧表示します。json データソースの、あらかじめ用意されてテスト済みの設定です (docs/sources.md の Presets)。それぞれに、埋めるカード、人が入力するフィールド (ヘルプ、パターン、例付き)、必要なシークレットとその入手方法、更新頻度とカードが最後のデータを保持する期間、そして誰のデータをどの規約のもとで読み取るかが示されます。

POST /api/sources に preset、settings、secrets を指定してプリセットからソースを作成し、POST /api/sources/test でプレビューします。

一覧に表示されるとおりの、1 つのソースプリセット。

プロジェクトのデータソースを新しい順に、1 ページ最大 200 件で一覧表示します。データソースは、外部のアドレスからスケジュールに従って 1 枚のカードの動的プロパティを最新に保ちます (docs/sources.md)。各ソースには、最後の試行、最後の成功、最後に書き込んだ変更、次回の実行、失敗回数、直近のエラーというステータスが表示されます。

シークレットは返されません。それぞれ、マスクされたヒント付きの「設定済み」として表示されます。次のページには next_cursor を after として渡します。これ以上ない場合は null です。

外部のアドレスから 1 枚のカードの動的プロパティを書き込むデータソースを作成します。kind はアダプターを選びます（ics は iCalendar または webcal:// のアドレスを読み取ります）。config には種類ごとの設定を、secrets にはその認証情報を指定します。認証情報は暗号化して保存され、マスクされたヒントとしてのみ表示されます。

または、kind と config の代わりにプリセット (GET /api/source-presets) を指定し、その settings と secrets を渡します。ソースは、プリセットが設定を組み立てる json ソースになり、preset と settings とともに返され、更新間隔と有効期間はプリセットの値が既定になります。プリセットが埋めるのは、それが挙げるカードだけです (source_target_unsupported)。

ソースは数秒以内に実行され、その後は refresh_seconds ごとに実行されます。実行に失敗しても書き込みは行われません。カードは最後に成功したドキュメントを保持し、ソースのステータスにエラーが表示されます。1 つのソースが書き込めるカードは 1 枚 (source_target_taken) で、そのカードはこの種類が埋められるものでなければならず (source_target_unsupported)、組織のソースは最大 200 です (source_limit_reached)。

まず POST /api/sources/test で、ソースが書き込むドキュメントを確認してください。source.created を追加します。同じ Idempotency-Key での完全に同一の再試行には、24 時間にわたり同じ応答が返ります。

何も保存せず、何も書き込まずにデータソースをプレビューします。アドレスを取得し、対象カード向けに応答を整形し、ドキュメントをカードで検証したうえで、ドキュメント、カードがそれを受け入れるかどうか（valid。受け入れない場合は validation_error がパスを示します）、実行時の警告とカウントを返します。

保存済みのソースを、他のメンバーを上書き値としてテストするには source_id を渡します (settings はプリセットから作成したソース自身の settings を上書きします)。そうでない場合は、target と、kind と config、または preset、settings、secrets が必須です。保存済みソースが保持するシークレットは、上書きによって接続先が変わらない限り、保存されたまま使われます（source_secret_required）。

取得または整形の失敗は、固定の source_error を伴う source_test_failed です。組織あたり毎分最大30回のプレビューです。

ステータス付きのデータソース 1 件。ETag はリビジョンで、次の変更時の If-Match に使います。

データソースを変更します。config は設定全体を置き換え、secrets はマージされます（文字列で設定または置換、null で削除）。

プリセットから作成したソースは、config の代わりに settings を受け取ります。指定した設定ごとにその値が置き換わり、null で任意の設定を削除し、それ以外は元の値を保ち、設定はプリセットから組み立て直されます (そのようなソースに config を指定すると config で invalid_request になり、ほかのソースに settings を指定すると settings で invalid_request になります)。シークレットの名前はプリセットが定める名前です。

送信しなかったシークレットは、変更によってソースの向き先が保存済みのスコープの範囲外になる場合を除き、値を保持します（secrets.<name> の source_secret_required: 再入力してください）。

ターゲット、config、シークレット、refresh_seconds、enabled のいずれかを変更すると、失敗回数がリセットされ、ソースが数秒以内に実行されます。名前の変更ではそうなりません。enabled を false にするとスケジュールが止まり、カードは最後のドキュメントを保持します。If-Match はリビジョンを保護します。source.updated を追加します。

データソースを削除します。カードは、ソースが最後に書き込んだドキュメントを保持します。If-Match はリビジョンを保護します。source.deleted を追加します。

予約システムの部屋を読み取るデータソース（種類 momentus）の部屋のマッピングです。データソースが提供していてもどのスクリーンにも表示されていない部屋（summary.unmapped_rooms）と、部屋またはエリアのドキュメントを読むのに、それを指す値がないスクリーン（ステータスが missing または unknown のスクリーン。値が表記違いの部屋であれば候補も示します）を返します。

部屋はデータソースの最後に成功した更新のものです。何も取得されません。部屋のない種類は source_has_no_rooms を返します。

ソースをその場で（最大 60 秒）すぐに同期し、新しいステータス付きで返します。同期に失敗した場合は、status.state が error のソースとエラーを添えて 200 で応答し、書き込みは行いません。更新するとソースは最初からやり直しになり、失敗回数がリセットされ、アドレスは全体が読み取られます。スケジュールされた同期がソースを使用中のときは source_busy (Retry-After) になります。

1 つのソースにつき 1 分あたり最大 6 回の同期です。