enterprise_ai.storage
Source : sdks/python/src/enterprise_ai/storage/__init__.py. Retour à l'index de la référence du SDK Python.
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 StorageClient
Stockage. Profils de stockage : les buckets et conteneurs du client dans lesquels la plateforme écrit (exports d'audit, preuves, documents, médias, exports, sauvegardes), avec leur référence d'identifiants et leurs capacités découvertes par de vrais appels.
Resource
StorageClient.checks
checks(profile_id: str, limit: int | None = None) -> Any
Lister les vérifications d'un profil. Historique des vérifications de capacités du profil, de la plus récente à la plus ancienne : statut, capacités trouvées, capacités manquantes, sonde d'écriture lancée ou non, erreur, durée en millisecondes et auteur. Une seule page (next_cursor vaut toujours null). Mêmes lecteurs que la liste.
Route : /v1/storage/profiles/{profile_id}/checks (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
limit | int | None | None | non | Nombre maximal de vérifications, de 1 à 500, 50 par défaut. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les vérifications d'un profil ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.create_profile
create_profile(name: str, provider: str, bucket: str, scope: str | None = None, endpoint: str | None = None, region: str | None = None, key_prefix: str | None = None, credential_ref: str | None = None, auth: dict[str, Any] | None = None, encryption: dict[str, Any] | None = None, purposes: list[str] | None = None, presign_prefixes: list[str] | None = None, required_capabilities: list[str] | None = None, options: dict[str, Any] | None = None, description: str | None = None) -> Any
Créer un profil de stockage. Crée un profil au statut unverified et répond 201. Demande tenant_admin pour la portée tenant (dans un tenant) ou platform_admin pour la portée platform (403 storage_scope_forbidden), et la décision de politique storage.profile.create. Audité (storage.profile.create).
Route : /v1/storage/profiles (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | str | oui | Nom unique du profil dans sa portée : 2 à 63 caractères, lettres minuscules, chiffres et tirets, commençant par une lettre ou un chiffre. | |
provider | str | oui | Fournisseur de stockage : aws_s3, ibm_cos, seaweedfs, s3_compatible, azure_blob ou gcs. | |
bucket | str | oui | Nom du bucket ou du conteneur : 3 à 222 caractères, lettres minuscules, chiffres, points, tirets et soulignés, commençant et finissant par une lettre ou un chiffre, sans ... | |
scope | str | None | None | non | tenant (par défaut) pour un profil du tenant de l'appelant, platform pour un profil partagé par la plateforme (administrateur de la plateforme seulement). |
endpoint | str | None | None | non | Adresse HTTPS du service de stockage, 500 caractères au plus. Obligatoire pour ibm_cos, seaweedfs et s3_compatible ; facultative sinon. |
region | str | None | None | non | Région du bucket, 64 caractères au plus. |
key_prefix | str | None | None | non | Préfixe ajouté à chaque clé d'objet écrite par ce profil, 512 caractères au plus ; vide par défaut. |
credential_ref | str | None | None | non | Référence du secret, 210 caractères au plus : openbao://<chemin> pour un profil de tenant, env://EAI_CRED_<NOM> pour un profil de plateforme. Inutilisée avec workload_identity. La valeur secrète n'est jamais envoyée. |
auth | dict[str, Any] | None | None | non | Paramètres d'authentification non secrets : method (sigv4 pour la famille S3, aussi ibm_iam pour IBM COS ; shared_key, sas, entra_client_secret ou workload_identity pour Azure ; service_account pour GCS) et, selon le besoin, account, tenant_id, client_id, service_instance_id, token_url, scope. account est obligatoire pour Azure ; workload_identity est réservé aux profils de plateforme. |
encryption | dict[str, Any] | None | None | non | Chiffrement côté serveur, {mode: provider_default} par défaut. Modes : provider_default, sse-s3, sse-kms pour la famille S3 ; provider_default, encryption-scope (avec encryption_scope) pour Azure ; provider_default, cmek (avec kms_key_id) pour GCS. |
purposes | list[str] | None | None | non | Usages du profil, jusqu'à 10 parmi audit_worm, evidence, documents, media, exports, backups, general. audit_worm demande verrouillage d'objet, rétention et intégrité ; evidence demande verrouillage d'objet et intégrité. |
presign_prefixes | list[str] | None | None | non | Préfixes de clés accessibles par l'API (URL présignées, liste, suppression), jusqu'à 20. Vide par défaut : aucune clé n'est accessible. |
required_capabilities | list[str] | None | None | non | Capacités que le profil doit avoir en plus de celles de ses usages, jusqu'à 20 parmi versioning, object_lock, legal_hold, retention, multipart, presign, sse, kms, storage_classes, lifecycle, replication, integrity. |
options | dict[str, Any] | None | None | non | Options du fournisseur : path_style (adressage par chemin pour S3) et storage_class. Toute autre clé est refusée. |
description | str | None | None | non | Description libre, 500 caractères au plus. |
Retour : Any. Réponse JSON décodée de l'opération « Créer un profil de stockage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.delete_object
delete_object(profile_id: str, key: str, version_id: str | None = None) -> Any
Supprimer un objet d'un profil. Supprime un objet (ou une de ses versions) à l'intérieur des préfixes de présignature du profil. Un profil qui sert audit_worm ou evidence ne supprime jamais par l'API (409 storage_object_protected) ; un refus de rétention du stockage est renvoyé tel quel. Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.object.delete ; audité avec la clé complète et la version. Autres erreurs : 403 storage_key_out_of_scope, 422 storage_key_invalid, 409 storage_profile_disabled.
Route : /v1/storage/profiles/{profile_id}/objects/delete (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
key | str | oui | Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature ; aucun caractère de contrôle, pas de / initial, aucun segment . ou ... | |
version_id | str | None | None | non | Version de l'objet à supprimer sur un bucket versionné, de 1 à 1024 caractères. Omettez-la pour supprimer la version courante. |
Retour : Any. Réponse JSON décodée de l'opération « Supprimer un objet d'un profil ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.delete_profile
delete_profile(profile_id: str) -> Any
Supprimer un profil de stockage. Supprime le profil (le bucket et ses objets ne sont pas touchés) et répond 204. Demande tenant_admin pour un profil de tenant, platform_admin pour un profil de plateforme (403 storage_scope_forbidden), et la décision de politique storage.profile.delete. L'événement d'audit storage.profile.delete enregistre le fournisseur, le bucket et le nombre d'exports d'audit qui l'utilisaient. Identifiant inconnu : 404 storage_profile_not_found.
Route : /v1/storage/profiles/{profile_id} (DELETE).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. |
Retour : Any. Réponse JSON décodée de l'opération « Supprimer un profil de stockage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.get
get(profile_id: str, key: str, purpose: str | None = None) -> Any
Émettre une URL présignée. Émet une URL présignée pour lire (GET) ou écrire (PUT) un objet directement dans le bucket, et répond 201 avec l'identifiant de l'autorisation, l'URL, la méthode, la clé complète, la durée de vie et l'échéance. La clé doit se trouver dans les préfixes de présignature (403 storage_key_out_of_scope) et le profil doit avoir une capacité presign vérifiée et récente (409 storage_capability_missing). La durée de vie ne peut dépasser EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 par défaut, jamais plus de 604800 ; 422 storage_presign_expiry_invalid). Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.presign.read ou storage.presign.write. L'autorisation est enregistrée avec un SHA-256 de l'URL (jamais l'URL elle-même) et auditée.
Route : /v1/storage/profiles/{profile_id}/presign (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
key | str | oui | Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature du profil. | |
purpose | str | None | None | non | Libellé libre de la raison de l'émission, enregistré avec l'autorisation ; 200 caractères au plus. |
Retour : Any. Réponse JSON décodée de l'opération « Émettre une URL présignée ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.get_profile
get_profile(profile_id: str) -> Any
Lire un profil de stockage. Un profil de stockage avec son statut, ses capacités découvertes, sa date de vérification, ses capacités manquantes et nécessaires et sa dernière erreur. Jamais une valeur secrète. Mêmes lecteurs que la liste. Identifiant inconnu : 404 storage_profile_not_found.
Route : /v1/storage/profiles/{profile_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. |
Retour : Any. Réponse JSON décodée de l'opération « Lire un profil de stockage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.list_objects
list_objects(profile_id: str, prefix: str | None = None, limit: int | None = None, cursor: str | None = None) -> Any
Lister les objets d'un profil. Objets rangés sous un préfixe à l'intérieur des préfixes de présignature du profil : clé relative au préfixe de clé du profil (utilisable pour la présignature et la suppression), clé stockée, taille, ETag, type de contenu, SHA-256, version, dernière modification et classe de stockage. Demande tenant_admin, developer, agent ou auditor (profil de plateforme : platform_admin) et la décision de politique storage.object.list ; la liste est auditée. Erreurs : 422 storage_prefix_required si prefix est omis et que le profil n'a pas exactement un préfixe de présignature, 403 storage_key_out_of_scope hors des préfixes de présignature, 409 storage_profile_disabled.
Route : /v1/storage/profiles/{profile_id}/objects (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
prefix | str | None | None | non | Préfixe de clé à lister, relatif au préfixe de clé du profil et à l'intérieur d'un de ses préfixes de présignature ; 1024 caractères au plus. Par défaut, le seul préfixe de présignature du profil. |
limit | int | None | None | non | Nombre maximal d'objets dans une page, de 1 à 500, 50 par défaut. |
cursor | str | None | None | non | Jeton de continuation opaque du stockage, renvoyé dans next_cursor par la page précédente ; 4096 caractères au plus. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les objets d'un profil ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.list_profiles
list_profiles(provider: str | None = None, purpose: str | None = None, scope: str | None = None, limit: int | None = None) -> Any
Lister les profils de stockage. Profils de stockage visibles par l'appelant, triés par portée puis par nom, chacun avec ses needed_capabilities (capacités exigées plus celles que demandent ses usages). Une seule page : next_cursor vaut toujours null. Demande platform_admin, ou un principal de tenant avec tenant_admin, security_officer, developer ou auditor.
Route : /v1/storage/profiles (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
provider | str | None | None | non | Seulement les profils de ce fournisseur, par exemple aws_s3 ou azure_blob. |
purpose | str | None | None | non | Seulement les profils qui servent cet usage, par exemple audit_worm ou documents. |
scope | str | None | None | non | Seulement les profils de cette portée : tenant ou platform. |
limit | int | None | None | non | Nombre maximal de profils, de 1 à 500, 50 par défaut. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les profils de stockage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.presign
presign(profile_id: str, key: str, scope: str, purpose: str | None = None, content_type: str | None = None, expires_seconds: int | None = None) -> Any
Émettre une URL présignée. Émet une URL présignée pour lire (GET) ou écrire (PUT) un objet directement dans le bucket, et répond 201 avec l'identifiant de l'autorisation, l'URL, la méthode, la clé complète, la durée de vie et l'échéance. La clé doit se trouver dans les préfixes de présignature (403 storage_key_out_of_scope) et le profil doit avoir une capacité presign vérifiée et récente (409 storage_capability_missing). La durée de vie ne peut dépasser EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 par défaut, jamais plus de 604800 ; 422 storage_presign_expiry_invalid). Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.presign.read ou storage.presign.write. L'autorisation est enregistrée avec un SHA-256 de l'URL (jamais l'URL elle-même) et auditée.
Route : /v1/storage/profiles/{profile_id}/presign (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
key | str | oui | Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature du profil. | |
scope | str | oui | Sens de l'URL : read donne une URL GET, write une URL PUT. | |
purpose | str | None | None | non | Libellé libre de la raison de l'émission, enregistré avec l'autorisation ; 200 caractères au plus. |
content_type | str | None | None | non | Type de contenu transmis au stockage lors de la signature de l'URL (le type que l'envoi doit transmettre) ; 200 caractères au plus. |
expires_seconds | int | None | None | non | Durée de vie de l'URL en secondes, 900 par défaut, au plus EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 par défaut) et jamais plus de 604800. |
Retour : Any. Réponse JSON décodée de l'opération « Émettre une URL présignée ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.put
put(profile_id: str, key: str, data: bytes, content_type: str | None = None, purpose: str | None = None, headers: dict[str, str] | None = None) -> Any
Émettre une URL présignée. Émet une URL présignée pour lire (GET) ou écrire (PUT) un objet directement dans le bucket, et répond 201 avec l'identifiant de l'autorisation, l'URL, la méthode, la clé complète, la durée de vie et l'échéance. La clé doit se trouver dans les préfixes de présignature (403 storage_key_out_of_scope) et le profil doit avoir une capacité presign vérifiée et récente (409 storage_capability_missing). La durée de vie ne peut dépasser EAI_STORAGE_PRESIGN_MAX_SECONDS (3600 par défaut, jamais plus de 604800 ; 422 storage_presign_expiry_invalid). Demande tenant_admin, developer ou agent (profil de plateforme : platform_admin) et la décision de politique storage.presign.read ou storage.presign.write. L'autorisation est enregistrée avec un SHA-256 de l'URL (jamais l'URL elle-même) et auditée.
Route : /v1/storage/profiles/{profile_id}/presign (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
key | str | oui | Clé de l'objet relative au préfixe de clé du profil, de 1 à 1024 caractères, dans un préfixe de présignature du profil. | |
data | bytes | oui | Objet, sens et durée de vie de l'URL présignée. | |
content_type | str | None | None | non | Type de contenu transmis au stockage lors de la signature de l'URL (le type que l'envoi doit transmettre) ; 200 caractères au plus. |
purpose | str | None | None | non | Libellé libre de la raison de l'émission, enregistré avec l'autorisation ; 200 caractères au plus. |
headers | dict[str, str] | None | None | non | En-têtes de l'événement, valeurs textuelles. Le contexte de trace y est ajouté. |
Retour : Any. Réponse JSON décodée de l'opération « Émettre une URL présignée ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.update_profile
update_profile(profile_id: str, **changes: Any) -> Any
Modifier un profil de stockage. Modifie les champs fournis ; le profil fusionné est validé comme un nouveau. Un changement de fournisseur, de point d'accès, de région, de bucket, de auth, de credential_ref, de encryption ou d'options efface les capacités et remet le statut à unverified ; status: disabled désactive le profil, status: active sur un profil désactivé le rend unverified. Ajouter l'usage audit_worm sans un tel changement demande une capacité de verrouillage d'objet vérifiée (409 storage_capability_missing). Demande tenant_admin (profil de plateforme : platform_admin) et la décision de politique storage.profile.update ; audité avec les champs modifiés.
Route : /v1/storage/profiles/{profile_id} (PATCH).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
**changes | Any | non | Champs du profil de stockage à modifier. |
Retour : Any. Réponse JSON décodée de l'opération « Modifier un profil de stockage ».
Erreurs levées : les erreurs typées du transport (Erreurs).
StorageClient.verify_profile
verify_profile(profile_id: str, probe_write: bool | None = None) -> Any
Vérifier les capacités d'un profil. Découvre les capacités du bucket par de vrais appels et les enregistre. Demande tenant_admin ou security_officer (profil de plateforme : platform_admin) et la décision de politique storage.profile.verify. Un profil désactivé répond 409 storage_profile_disabled.
Route : /v1/storage/profiles/{profile_id}/verify (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
profile_id | str | oui | Identifiant (UUID) du profil de stockage. | |
probe_write | bool | None | None | non | Si vrai (par défaut), un objet sonde est écrit avec le chiffrement, la classe de stockage et la conservation légale configurés, relu puis supprimé, pour vérifier les classes de stockage et l'intégrité. Il est ignoré si le bucket a une rétention par défaut. Si faux, ces deux capacités restent non vérifiées. |
Retour : Any. Réponse JSON décodée de l'opération « Vérifier les capacités d'un profil ».
Erreurs levées : les erreurs typées du transport (Erreurs).
Fonctions
confirm_deleted
confirm_deleted(answer: Any) -> Any
Renvoie une suppression d'objet uniquement si le serveur indique deleted: true.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
answer | Any | oui | Réponse de POST /v1/storage/profiles/{profile_id}/objects/delete à contrôler. |
Retour : Any. La même réponse, inchangée ; sinon storage_delete_unconfirmed est levée.
Erreurs levées : EaiError.