接続 API

プロジェクトの接続を新しい順に、1 ページ最大 200 件で一覧表示します。次のページには next_cursor を after として渡します。

接続は、無人で動作するソース向けの、プロジェクトが再利用できる Microsoft または Google へのアクセスです。microsoft365 または google_calendar のデータソース、Power BI 接続、SharePoint メディア同期アカウントは、独自の認証情報を持つ代わりに、config.connection_id で接続を 1 つ指定します (docs/connections.md)。

シークレット、キー、更新トークンは返されません。secret は、保持されているかどうかと、秘密ではないヒントを示します。読み取りに同意リンクが含まれることはありません。

Microsoft (provider microsoft) または Google (provider google) への接続を作成します。モード own_app はお客様自身のアプリケーションです。Microsoft の場合は config.tenant_id (ディレクトリ ID またはプライマリドメイン。common、organizations、consumers は拒否されます)、config.client_id、secret (アプリのクライアントシークレットの 1 つの値)、Google の場合は secret がサービスアカウントの JSON キーファイルです。

シークレットは封印して保存され、返されることはありません。モード screenrig_app は screenRIG 自身のアプリケーションを使い、config も secret も受け付けません。接続は pending_consent で作成され、レスポンスには、完了する人向けの 1 回限りのリンク consent_url (consent_expires_at まで有効) が含まれます。

Microsoft の場合は Microsoft 365 の管理者で、テナントに対する screenRIG のアプリケーションに同意します。続いてブラウザーが Microsoft の示すテナントにサインインするため、接続には確認されたテナントが記録され、コールバックが主張するだけのテナントは記録されません。

Google の場合はアカウントの所有者で、アカウントが見られるカレンダーへの読み取り専用アクセスを許可します。screenRIG は更新トークンを封印して保持し、アカウントのアドレスも保持します。リンクは 1 回の同意の認証情報です。その人にだけ送ってください。

プロバイダー向けの screenRIG のアプリケーションがないサーバーは 409 connection_app_not_configured を返し、own_app の接続は引き続き動作します。組織はすべてのプロジェクトを通じて最大 50 件の接続を持てます (connection_limit_reached)。connection.created を追記します。

同じ Idempotency-Key での同一の再試行は、同じ接続を返します (screenrig_app の再試行では新しい同意リンクが発行され、最初のリンクは置き換えられます)。

1 件の接続を、ステータス、最後のエラー、最後のテストとともに返します。

接続の名前を変更します。モード own_app では認証情報も変更できます。config.tenant_id と config.client_id (Microsoft)、または secret (送信したシークレットは封印済みのものを置き換え、省略したものは保持されます)。モード screenrig_app の接続は名前の変更のみ可能です。同意した人を変えるには、もう一度接続します (POST /api/connections/{id}/connect)。

認証情報を変更すると、接続は ready に戻り、last_error と last_test が消去され、古い認証情報向けに発行されたすべてのトークンが失効します。connection.updated を追記します。If-Match がリビジョンを保護します。

どこからも読み取られていない接続を削除します。データソース、Power BI 接続、メディア同期アカウントが読み取っている間は、それらを示す resource_conflict が返されます (used_by にその種類と ID が一覧されます)。

削除してもベンダー側は終了しません。Microsoft 365 のテナントは、管理者が削除するまで screenRIG のアプリケーションを保持し、Google アカウントは、所有者が取り消すまでその許可を保持します。connection.deleted を追記します。If-Match がリビジョンを保護します。

接続でサインインし、その結果を last_test として保存します。

Microsoft の場合、チェックは credentials (Microsoft がテナント向けにアプリトークンを発行したか) と permissions (アプリのトークンが Calendars.Read、Sites.Selected、Files.Read.All、Sites.Read.All、Place.Read.All のどれを持つか) です。どれも持たないアプリはチェックに失敗し、Sites.Selected のみの場合は、SharePoint の各サイトに付与が必要なため警告になります。

Google の場合、チェックは credentials です。Google がサービスアカウント、または許可したアカウントの更新トークンを受け入れたかを確認し、レスポンスには、カレンダーを見えるようにしておく必要があるアカウントが示されます。拒否はチェックの失敗で、接続は last_error とともに error になります。成功すると ready に戻ります。

カレンダーの共有、メールボックスのアクセスポリシー、サイトへの付与は判定しません。これらは、ソースまたは同期が実行されたときに確かめられます。1 組織あたり 1 分間に最大 30 回です。

モード screenrig_app の接続向けに、1 回限りの新しい同意リンク (consent_url、consent_expires_at まで有効) を作成します。完了する人、つまり Microsoft 365 の管理者または Google アカウントの所有者に送ってください。以前のリンクはすべて置き換えられます。

動作している接続は、新しい同意が完了するまでそのままなので、この操作は、error になった接続 (同意の削除、アクセスの取り消し) の更新や、別のテナントまたはアカウントへの切り替えにも使えます。リンクは同意の認証情報です。その人にだけ送ってください。

その人が完了すると、ブラウザーは GET /oauth/connections/{provider}/callback に戻り、ダッシュボードの接続のページに転送されます。このページは status と last_error を読み取ります。モード own_app の接続には同意のステップがありません (409 resource_conflict)。プロバイダー向けの screenRIG のアプリケーションがないサーバーは 409 connection_app_not_configured を返します。

モード screenrig_app の接続で、Microsoft 365 の管理者が管理者の同意ページを経た後 (およびそれに続くサインインのステップの後にもう一度)、Microsoft がそのブラウザーを送り返す先です。

認証情報は含まれません。クエリ内の署名付き state が唯一の根拠で、それが示すものを読み取る前に検証され、接続の保留中の同意である間だけ受け付けられます。

最初の戻りではテナントが示されますが、これは認証されていません。レスポンスはそのテナントのサインインへのリダイレクトで、そのコードはアプリケーションのシークレットと、このサーバーだけが導出できる PKCE ベリファイアで引き換えられます。接続に記録されるのは ID トークンが運ぶテナントで、クライアントクレデンシャルのトークンによって、アプリケーションがそこで自身の権限を持つことが証明された後に記録されます。

検証済みの state の後は、どの結果でも、ダッシュボードの接続のページ (/dashboard/connections/{id}?consent=connected または ?consent=failed) にリダイレクトされ、そのページは status と last_error を読み取ります。エラーテキストは、固定の文と Microsoft 自身のエラーレスポンス (AADSTS コード) から組み立てられ、コールバックのクエリが運んだ内容からは決して作られません。

不明、期限切れ、使用済み、置き換え済み、または削除された接続の state は、何も示さないページを表示します。コールバックが登録されている API ホストでのみ応答します。

モード screenrig_app の接続で、アカウントの所有者が同意ページを経た後に、Google がそのブラウザーを送り返す先です。

認証情報は含まれません。クエリ内の署名付き state が唯一の根拠で、それが示すものを読み取る前に検証され、接続の保留中の同意である間だけ受け付けられます。screenRIG は、アプリケーションのシークレットと、このサーバーだけが導出できる PKCE ベリファイアでコードを引き換え、カレンダーのスコープが許可されていること (同意ページで人が外せます) と更新トークンがあることを確認し、その呼び出しで Google が返した ID トークンから許可したアカウントを読み取り、更新トークンを封印して保存し、connection.connected を追記します。

検証済みの state の後は、どの結果でも、ダッシュボードの接続のページ (/dashboard/connections/{id}?consent=connected または ?consent=failed) にリダイレクトされ、そのページは status と last_error を読み取ります。不明、期限切れ、使用済み、置き換え済み、または削除された接続の state は、何も示さないページを表示します。

コールバックが登録されている API ホストでのみ応答します。