Verbindungen-API

Listet die Verbindungen des Projekts auf, neueste zuerst, höchstens 200 pro Seite; geben Sie next_cursor als after für die nächste zurück.

Eine Verbindung ist der wiederverwendbare Zugriff des Projekts auf Microsoft oder Google für Quellen, die unbeaufsichtigt laufen: Eine microsoft365- oder google_calendar-Datenquelle, eine Power-BI-Verbindung und ein SharePoint-Mediensynchronisierungskonto nennen in config.connection_id eine, statt eigene Zugangsdaten mitzubringen (docs/connections.md).

Ein Secret, ein Schlüssel oder ein Aktualisierungs-Token wird nie zurückgegeben: secret zeigt, ob eines gehalten wird, und einen Hinweis, der nicht geheim ist. Ein Lesezugriff enthält nie einen Zustimmungslink.

Legt eine Verbindung zu Microsoft (provider microsoft) oder Google (provider google) an. Der Modus own_app ist die eigene Anwendung des Kunden: bei Microsoft config.tenant_id (die Verzeichnis-ID oder primäre Domain; common, organizations und consumers werden abgelehnt), config.client_id und secret (der Wert eines der Client-Secrets der Anwendung); bei Google ist secret die JSON-Schlüsseldatei des Dienstkontos.

Das Secret wird versiegelt und nie zurückgegeben. Der Modus screenrig_app nutzt die eigene Anwendung von screenRIG und nimmt weder config noch secret entgegen: Die Verbindung wird als pending_consent angelegt, und die Antwort enthält consent_url, einen einmaligen Link (gültig bis consent_expires_at) für die Person, die ihn abschließt.

Bei Microsoft ist das ein Microsoft-365-Administrator, der der Anwendung von screenRIG für den Mandanten zustimmt; der Browser meldet sich dann bei dem Mandanten an, den Microsoft nennt, sodass die Verbindung den bestätigten Mandanten speichert, nie einen, den ein Callback nur behauptet.

Bei Google ist das der Kontoinhaber, der lesenden Zugriff auf die Kalender gewährt, die das Konto sehen kann; screenRIG bewahrt das Aktualisierungs-Token versiegelt auf, dazu die Adresse des Kontos. Der Link ist eine Zugangsberechtigung für eine einzige Zustimmung: Senden Sie ihn nur an diese Person.

Ein Server ohne die Anwendung von screenRIG für den Anbieter antwortet mit 409 connection_app_not_configured, und own_app-Verbindungen funktionieren weiter. Eine Organisation hat höchstens 50 Verbindungen über alle ihre Projekte (connection_limit_reached). Hängt connection.created an.

Ein exakter Wiederholungsversuch mit demselben Idempotency-Key gibt dieselbe Verbindung zurück (ein screenrig_app-Wiederholungsversuch erhält einen neuen Zustimmungslink, der den ersten ersetzt).

Eine Verbindung, mit ihrem Status, ihrem letzten Fehler und ihrem letzten Test.

Ändert den Namen einer Verbindung oder im Modus own_app ihre Zugangsdaten: config.tenant_id und config.client_id (Microsoft) oder secret (ein gesendetes Secret ersetzt das versiegelte; ein weggelassenes bleibt erhalten). Eine Verbindung im Modus screenrig_app kann nur umbenannt werden: Verbinden Sie sie erneut (POST /api/connections/{id}/connect), um zu ändern, wer zugestimmt hat.

Eine Änderung der Zugangsdaten setzt die Verbindung auf ready zurück, löscht last_error und last_test und zieht jedes für die alten Zugangsdaten ausgestellte Token zurück. Hängt connection.updated an. If-Match schützt die Revision.

Löscht eine Verbindung, über die nichts liest. Solange eine Datenquelle, eine Power-BI-Verbindung oder ein Mediensynchronisierungskonto sie nutzt, lautet die Antwort resource_conflict und nennt sie (used_by listet ihren Typ und ihre ID).

Das Löschen beendet nicht die Seite des Anbieters: Ein Microsoft-365-Mandant behält die Anwendung von screenRIG, bis sein Administrator sie entfernt, und ein Google-Konto behält seine Freigabe, bis sein Inhaber sie widerruft. Hängt connection.deleted an. If-Match schützt die Revision.

Meldet sich mit der Verbindung an und speichert die Antwort als last_test.

Bei Microsoft sind die Prüfungen credentials (Microsoft hat ein App-Token für den Mandanten ausgestellt) und permissions (welche von Calendars.Read, Sites.Selected, Files.Read.All, Sites.Read.All und Place.Read.All das Token der App trägt; eine App, die keine hält, besteht die Prüfung nicht, und Sites.Selected allein ist eine Warnung, weil jede SharePoint-Site eine Freigabe braucht).

Bei Google ist die Prüfung credentials: Google hat das Dienstkonto oder das Aktualisierungs-Token des gewährenden Kontos akzeptiert, und die Antwort nennt das Konto, für das die Kalender sichtbar sein müssen. Eine Ablehnung ist eine fehlgeschlagene Prüfung und setzt die Verbindung mit last_error auf error; ein Erfolg setzt sie auf ready zurück.

Sie beurteilt weder die Freigabe eines Kalenders noch eine Postfach-Zugriffsrichtlinie noch eine Site-Freigabe; das beweist eine Quelle oder Synchronisierung, wenn sie läuft. Höchstens 30 pro Minute und Organisation.

Erzeugt einen neuen einmaligen Zustimmungslink (consent_url, gültig bis consent_expires_at) für eine Verbindung im Modus screenrig_app, den Sie an die Person senden, die ihn abschließt: den Microsoft-365-Administrator oder den Google-Kontoinhaber. Er ersetzt jeden früheren Link.

Eine funktionierende Verbindung bleibt unverändert, bis die neue Zustimmung abgeschlossen ist; damit lässt sich also auch eine Verbindung erneuern, die auf error gewechselt ist (Zustimmung entfernt, Zugriff widerrufen), oder auf einen anderen Mandanten oder ein anderes Konto umstellen. Der Link ist eine Zugangsberechtigung der Zustimmung: Senden Sie ihn nur an diese Person.

Wenn die Person fertig ist, kehrt der Browser zu GET /oauth/connections/{provider}/callback zurück und wird zur Seite der Verbindung im Dashboard weitergeleitet, das status und last_error liest. Eine Verbindung im Modus own_app hat keinen Zustimmungsschritt (409 resource_conflict); ein Server ohne die Anwendung von screenRIG für den Anbieter antwortet mit 409 connection_app_not_configured.

Wohin Microsoft den Browser eines Microsoft-365-Administrators nach der Administrator-Zustimmungsseite (und erneut nach dem darauf folgenden Anmeldeschritt) für eine Verbindung im Modus screenrig_app schickt.

Sie trägt keine Zugangsdaten: Der signierte State in der Abfrage ist die einzige Instanz, wird geprüft, bevor irgendetwas gelesen wird, was er nennt, und gilt nur, solange er die ausstehende Zustimmung der Verbindung ist.

Die erste Rückkehr nennt einen Mandanten, der nicht authentifiziert ist: Die Antwort ist eine Weiterleitung zur Anmeldung dieses Mandanten, deren Code mit dem Secret der Anwendung und einem PKCE-Verifier eingelöst wird, den nur dieser Server ableiten kann, und der Mandant, den das ID-Token trägt, ist der, den die Verbindung speichert, nachdem ein Client-Credentials-Token belegt, dass die Anwendung dort ihre Berechtigungen hält.

Jedes Ergebnis nach einem geprüften State leitet zur Seite der Verbindung im Dashboard weiter (/dashboard/connections/{id}?consent=connected oder ?consent=failed), das status und last_error liest; der Fehlertext wird aus festen Sätzen und der eigenen Fehlerantwort von Microsoft (deren AADSTS-Code) gebildet, nie aus dem, was die Abfrage des Callbacks trug.

Ein State, der unbekannt, abgelaufen, benutzt, ersetzt oder für eine gelöschte Verbindung ist, zeigt eine Seite, die nichts nennt. Antwortet nur auf dem API-Host, unter dem die Callbacks registriert sind.

Wohin Google den Browser des Kontoinhabers nach der Zustimmungsseite für eine Verbindung im Modus screenrig_app schickt.

Sie trägt keine Zugangsdaten: Der signierte State in der Abfrage ist die einzige Instanz, wird geprüft, bevor irgendetwas gelesen wird, was er nennt, und gilt nur, solange er die ausstehende Zustimmung der Verbindung ist. screenRIG löst den Code mit dem Secret der Anwendung und einem PKCE-Verifier ein, den nur dieser Server ableiten kann, verlangt, dass der Kalender-Bereich gewährt wurde (eine Person kann ihn auf der Zustimmungsseite abwählen) und ein Aktualisierungs-Token, liest das gewährende Konto aus dem ID-Token, das Google bei diesem Aufruf zurückgab, versiegelt das Aktualisierungs-Token und hängt connection.connected an.

Jedes Ergebnis nach einem geprüften State leitet zur Seite der Verbindung im Dashboard weiter (/dashboard/connections/{id}?consent=connected oder ?consent=failed), das status und last_error liest. Ein State, der unbekannt, abgelaufen, benutzt, ersetzt oder für eine gelöschte Verbindung ist, zeigt eine Seite, die nichts nennt.

Antwortet nur auf dem API-Host, unter dem die Callbacks registriert sind.