enterprise_ai.connectors

Source : sdks/python/src/enterprise_ai/connectors/__init__.py. Retour à l'index de la référence du SDK Python.

remarque

Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.

Classe ConnectorsClient

Connecteurs. Connector Hub : registre des connexions aux systèmes externes (applications SaaS, API, sources de données), leurs identifiants conservés côté serveur, les exécutions de synchronisation, le Credential Broker qui remet des baux de courte durée à la place des secrets, et la Webhook Gateway qui reçoit les événements signés des fournisseurs.

Resource

ConnectorsClient.create

create(manifest: dict[str, Any]) -> Any

Enregistrer un connecteur. Applique un manifeste Connector : crée ou met à jour le connecteur (apply_status : created ou updated). Les URL doivent être permises par la politique de sortie réseau ; OAuth2 demande auth.token_url ; les webhooks non signés sont refusés (422 invalid_manifest). Demande tenant_admin, developer ou application_owner. Audité sous connector.apply.

Route : /v1/connectors (POST).

Nom	Type	Défaut	Requis	Description
manifest	dict[str, Any]		oui	Connector Manifest du nouveau connecteur, envoyé comme corps de la requête.

Retour : Any. Réponse JSON décodée de l'opération « Enregistrer un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.delete

delete(name: str) -> Any

Supprimer un connecteur. Supprime le connecteur et ses identifiants dans le magasin de secrets. Demande tenant_admin. 404 connector_not_found. Audité sous connector.delete.

Route : /v1/connectors/{name} (DELETE).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.

Retour : Any. Réponse JSON décodée de l'opération « Supprimer un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.deliver_webhook

deliver_webhook(connector: str, payload: dict[str, Any], secret: str, tenant: str, delivery_id: str | None = None) -> Any

Recevoir un webhook de fournisseur. Point d'entrée du fournisseur, sans authentification de la plateforme. En-têtes : X-EAI-Tenant (slug du tenant, sinon 400 tenant_required), X-EAI-Signature (t=<secondes unix>,v1=<HMAC-SHA256 hexadécimal de "<t>." + corps brut> ; X-EAI-Timestamp peut porter l'horodatage), X-EAI-Delivery facultatif (identifiant de dédoublonnage). Étapes : 1. Le connecteur doit exister, être actif et avoir les webhooks activés (404 connector_not_found). 2. Signature vérifiée avec le webhook_secret enregistré ou la référence de secret du manifeste (401 invalid_signature) ; horodatage à moins de 5 minutes (401 webhook_replay) ; une livraison déjà acceptée répond 409 webhook_duplicate. 3. Le corps JSON est contrôlé comme contenu non fiable (injection de prompt bloquée), puis publié sous connectors.<nom>.webhook, ce qui peut lancer des runs déclenchés. Répond 202 avec delivery_id, event_id et triggered. Chaque livraison est enregistrée et auditée sous webhook.receive.

Route : /v1/webhooks/{connector} (POST).

Nom	Type	Défaut	Requis	Description
connector	str		oui	Nom du connecteur auquel le fournisseur envoie.
payload	dict[str, Any]		oui	Charge utile brute du fournisseur ; la signature est vérifiée sur ces octets exacts, quel que soit le type de contenu.
secret	str		oui	Secret partagé du webhook utilisé pour la signature HMAC-SHA256 X-EAI-Signature.
tenant	str		oui	Slug du tenant envoyé comme X-EAI-Tenant.
delivery_id	str | None	None	non	Identifiant de déduplication envoyé comme X-EAI-Delivery ; par défaut dlv- suivi d'un identifiant hexadécimal aléatoire.

Retour : Any. Réponse JSON décodée de l'opération « Recevoir un webhook de fournisseur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.get

get(name: str) -> Any

Lire un connecteur. Renvoie le connecteur avec son manifeste, son statut, son propriétaire et ses identifiants configurés (type, noms de champs, date de mise à jour). 404 connector_not_found.

Route : /v1/connectors/{name} (GET).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.

Retour : Any. Réponse JSON décodée de l'opération « Lire un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.lease

lease(connector: str, scopes: list[str] | None = None, ttl_seconds: int = 300, run_id: str | None = None) -> Any

Obtenir un bail d'identifiants. Émet un bail de courte durée sur un connecteur à la place de son secret (201) : lease_id, token (montré une seule fois), scopes, expires_at, ttl_seconds. Les scopes demandés doivent être déclarés par le connecteur (403 scope_not_allowed ; par défaut : tous) ; le connecteur doit être actif (409 connector_disabled). Avec on_behalf_of, l'utilisateur doit détenir la relation can_invoke sur le connecteur (403 relation_required). Demande tenant_admin, developer ou agent. Audité sous credential.lease.

Route : /v1/credentials/broker/lease (POST).

Nom	Type	Défaut	Requis	Description
connector	str		oui	Nom du connecteur.
scopes	list[str] | None	None	non	Scopes du bail, parmi ceux déclarés par le connecteur. Vide (par défaut) : tous.
ttl_seconds	int	300	non	Durée de vie du bail en secondes (30 à 3600, 600 par défaut).
run_id	str | None	None	non	Run pour lequel le bail est émis, enregistré avec lui.

Retour : Any. Réponse JSON décodée de l'opération « Obtenir un bail d'identifiants ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.leased

leased(connector: str, scopes: list[str] | None = None, ttl_seconds: int = 300) -> Iterator[Any]

Gestionnaire de contexte qui fournit un bail ; le jeton est effacé de la mémoire à la sortie.

Nom	Type	Défaut	Requis	Description
connector	str		oui	Nom du connecteur pour lequel obtenir un jeton.
scopes	list[str] | None	None	non	Portées demandées pour le jeton délégué, facultatives.
ttl_seconds	int	300	non	Durée de vie du bail en secondes (300 par défaut).

Retour : Iterator[Any]. La réponse de bail de POST /v1/credentials/broker/lease, vidée à la sortie du bloc with.

ConnectorsClient.list

list(**page: Any) -> Any

Lister les connecteurs. Connecteurs du tenant dans l'ordre des noms, chacun avec les types d'identifiants configurés (jamais leurs valeurs). Une seule page.

Route : /v1/connectors (GET).

Nom	Type	Défaut	Requis	Description
**page	Any		non	Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs.

Retour : Any. Réponse JSON décodée de l'opération « Lister les connecteurs ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.set_credentials

set_credentials(name: str, credentials: dict[str, Any]) -> Any

Enregistrer les identifiants d'un connecteur. Enregistre des identifiants dans le magasin de secrets et ne renvoie que le type et les noms de champs (201). Demande tenant_admin ou security_officer. Corps : kind plus ses champs : - oauth2_client : client_id, client_secret ; - oauth2_code : code, redirect_uri, code_verifier facultatif ; le code est échangé aussitôt auprès de l'URL de jeton (demande un oauth2_client enregistré, sinon 409 credential_unavailable) et conservé comme oauth2_token ; - api_key : api_key, header facultatif ; - service_account : private_key ou token, client_email et client_id facultatifs ; - basic : username, password ; - webhook_secret : secret. Un type inconnu ou des champs manquants répondent 400 invalid_request. Audité sous connector.credentials.write.

Route : /v1/connectors/{name}/credentials (POST).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.
credentials	dict[str, Any]		oui	Identifiants du connecteur, envoyés en écriture seule au Credential Broker.

Retour : Any. Réponse JSON décodée de l'opération « Enregistrer les identifiants d'un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.sync

sync(name: str, full: bool = False) -> Any

Lancer une synchronisation. Met en file une synchronisation (202) et publie connectors.<nom>.sync pour le worker. Le manifeste doit déclarer un mode de synchronisation (409 sync_disabled), le connecteur doit être actif (409 connector_disabled), les ressources doivent être lisibles (400 invalid_request) et aucune autre exécution ne doit être en file ou en cours (409 sync_in_progress). Une synchronisation incrémentale part du curseur de la dernière exécution réussie sauf avec full. La politique connector.sync est évaluée. Demande tenant_admin, developer ou agent. Audité sous connector.sync.

Route : /v1/connectors/{name}/sync (POST).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.
full	bool	False	non	Si vrai, ignore le curseur de la dernière exécution et synchronise tout. Faux par défaut.

Retour : Any. Réponse JSON décodée de l'opération « Lancer une synchronisation ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.sync_runs

sync_runs(name: str) -> Any

Lister les synchronisations d'un connecteur. Exécutions de synchronisation du connecteur, de la plus récente à la plus ancienne : mode, statut, ressources, curseur et dates.

Route : /v1/connectors/{name}/sync-runs (GET).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.

Retour : Any. Réponse JSON décodée de l'opération « Lister les synchronisations d'un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.test

test(name: str) -> Any

Tester un connecteur. Construit les en-têtes d'authentification à partir des identifiants enregistrés et, quand le manifeste a une URL de base, lui envoie un GET. Renvoie ok, credentials, http_status, latency_ms et un code error en cas d'échec (egress_denied, upstream_unavailable, erreurs d'identifiants) ; un test en échec est un 200 avec ok: false. La politique connector.test est évaluée. Demande tenant_admin, developer ou application_owner. Audité sous connector.test.

Route : /v1/connectors/{name}/test (POST).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.

Retour : Any. Réponse JSON décodée de l'opération « Tester un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.update

update(name: str, **changes: Any) -> Any

Modifier un connecteur. Modifie le statut ou le propriétaire. Désactiver un connecteur révoque immédiatement ses baux d'identifiants. Demande tenant_admin, developer ou application_owner. Audité sous connector.update.

Route : /v1/connectors/{name} (PATCH).

Nom	Type	Défaut	Requis	Description
name	str		oui	Nom du connecteur.
**changes	Any		non	Champs du connecteur à modifier, envoyés comme corps du PATCH.

Retour : Any. Réponse JSON décodée de l'opération « Modifier un connecteur ».

Erreurs levées : les erreurs typées du transport (Erreurs).

ConnectorsClient.webhook_deliveries

webhook_deliveries(**page: Any) -> Any

Lister les livraisons de webhooks. Livraisons de webhooks reçues, de la plus récente à la plus ancienne : connecteur, identifiant de livraison, validité de la signature, statut (accepted, rejected, duplicate), raison, SHA-256 de la charge utile et événement publié. La charge utile elle-même n'est pas conservée ici.

Route : /v1/webhooks/deliveries (GET).

Nom	Type	Défaut	Requis	Description
**page	Any		non	Options de pagination transmises à la liste : limit (nombre maximal d'éléments par page) et cursor (le next_cursor de la page précédente). Itérer sur la page renvoyée suit tous les curseurs.

Retour : Any. Réponse JSON décodée de l'opération « Lister les livraisons de webhooks ».

Erreurs levées : les erreurs typées du transport (Erreurs).

Fonctions

sign_webhook

sign_webhook(secret: str | bytes, payload: bytes, timestamp: int | None = None, tenant: str | None = None, delivery_id: str | None = None) -> dict[str, str]

En-têtes d'un webhook signé poussé vers la plateforme.

Nom	Type	Défaut	Requis	Description
secret	str | bytes		oui	Secret partagé du webhook, texte ou octets, clé du HMAC-SHA256.
payload	bytes		oui	Corps brut de la requête, en octets.
timestamp	int | None	None	non	Heure Unix en secondes placée dans t= ; par défaut l'heure courante.
tenant	str | None	None	non	Slug du tenant envoyé comme X-EAI-Tenant, facultatif.
delivery_id	str | None	None	non	Identifiant de déduplication envoyé comme X-EAI-Delivery, facultatif.

Retour : dict[str, str]. En-têtes X-EAI-Signature, plus X-EAI-Tenant et X-EAI-Delivery s'ils sont fournis.

verify_webhook

verify_webhook(secret: str | bytes, payload: bytes, header: str | None, tolerance: int = 300, now: float | None = None) -> bool

Vérifie X-EAI-Signature: t=<unix>,v1=<hex> sur "<t>.<raw body>".

Nom	Type	Défaut	Requis	Description
secret	str | bytes		oui	Secret partagé du webhook, texte ou octets.
payload	bytes		oui	Corps brut reçu, en octets.
header	str | None		oui	Valeur de l'en-tête X-EAI-Signature reçu ; None ou vide renvoie False.
tolerance	int	300	non	Écart maximal en secondes entre t et maintenant (300 par défaut).
now	float | None	None	non	Heure Unix courante en secondes ; par défaut time.time(), à fixer dans les tests.

Retour : bool. True si une signature v1 correspond (comparaison en temps constant) et que l'horodatage est récent, sinon False.