Transfert de site

Un paquet de site est une copie portable du modèle de contenu, du contenu, de l’historique éditorial, de la présentation, des paramètres et des fichiers médias d’un site EmDash. Importez un paquet de site pour déplacer un site vers un autre déploiement EmDash, y compris un déploiement qui utilise une autre base de données : SQLite, PostgreSQL ou Cloudflare D1.

Une importation écrit dans un nouveau site dont la zone de contenu est vide. EmDash vérifie l’ensemble du paquet avant d’écrire quoi que ce soit, exécute l’importation en petites étapes reprenables, relit le site importé et émet un reçu lorsque le résultat correspond au paquet.

Un paquet de site ne contient ni utilisateurs, ni identifiants, ni secrets. Il contient en revanche chaque entrée et chaque commentaire du site, y compris les adresses e-mail des auteurs et des commentateurs. Stockez-le et transmettez-le avec le même soin qu’une sauvegarde de base de données.

Choisir le bon type de copie

Utilisez une sauvegarde brute de la base de données pour restaurer un déploiement après une perte de données. Utilisez un paquet de site pour créer une nouvelle copie d’un site ailleurs.

Contenu d’un paquet de site

Un paquet de site contient :

• les collections, les champs, les types de blocs avec toutes leurs versions, les définitions de taxonomies, les définitions de relations et les définitions de champs de byline ;
• chaque entrée de contenu dans chaque langue, y compris les brouillons, les entrées planifiées, les entrées dans la corbeille, l’historique des révisions et les groupes de traduction ;
• les termes de taxonomie et les attributions de termes, les bylines et les crédits, les références de contenu et les enregistrements SEO ;
• les menus et éléments de menu, les zones de widgets et les widgets, les sections et les redirections ;
• les commentaires et les réactions aux commentaires, sauf si l’export exclut les commentaires ;
• les dossiers de médias, les métadonnées des médias et les octets de chaque fichier média prêt ; et
• les paramètres de site portables listés ci-dessous.

Le paquet stocke les valeurs JSON, comme les champs JSON et le Portable Text, avec les clés d’objet triées. Une valeur importée peut donc lister ses clés dans un ordre différent de celui de l’origine. Pour le reste, les valeurs sont inchangées.

Paramètres portables

Seuls ces paramètres sont exportés : site:title, site:tagline, site:logo, site:favicon, site:postsPerPage, site:dateFormat, site:timezone, site:social, site:seo, emdash:site_title, emdash:site_tagline et emdash:locale.

Le site cible conserve sa propre URL de site (site:url et emdash:site_url), son ID de site, son état de configuration et ses paramètres de sauvegarde. Une importation ne les écrase jamais.

Le plan d’importation demande s’il faut conserver le titre et le slogan de la cible, écrits par l’assistant de configuration, ou utiliser les valeurs du paquet. Par défaut, les valeurs du paquet sont utilisées.

Principals

Un compte utilisateur n’est jamais déplacé avec un paquet. Pour chaque utilisateur d’origine auquel font référence le contenu, les révisions, les médias, les bylines ou les commentaires, le paquet contient un principal : l’ID de l’utilisateur, son nom d’affichage et son adresse e-mail. Un principal n’a ni rôle, ni mot de passe, ni passkey, ni session, ni jeton.

Pendant l’importation, vous associez chaque principal à un utilisateur du site cible ou le laissez sans association. Consultez associer les auteurs aux utilisateurs cibles.

Commentaires

Les commentaires comprennent le nom et l’adresse e-mail de l’auteur, le corps, le statut, le fil de discussion, les horodatages et les métadonnées de modération. Le hachage de l’adresse IP et l’user agent ne sont pas exportés.

Les réactions conservent leur nombre. L’exportateur remplace chaque hachage de votant par une nouvelle valeur aléatoire, de sorte que la cible ne peut pas associer une réaction au visiteur qui l’a émise.

Ce qu’un paquet de site exclut

Un paquet de site ne contient jamais :

• les utilisateurs, sessions, passkeys, comptes OAuth, domaines autorisés, jetons d’API, clients OAuth, codes d’autorisation ou codes d’appareil ;
• le stockage, l’état ou les paramètres des plugins, y compris les secrets des plugins ;
• les paramètres autres que les paramètres portables, comme le secret de signature des aperçus ;
• les journaux d’audit, les limites de débit, les verrous d’édition, l’état des tâches planifiées, le journal des erreurs 404 ou l’historique des migrations ;
• les enregistrements d’utilisation des médias et les index de recherche, que l’importation reconstruit ;
• les clés de stockage, noms de buckets, noms de bases de données ou noms de bindings de l’origine ; ni
• les médias qui ne sont pas prêts, comme un téléversement incomplet.

Les médias d’un fournisseur de médias externe restent externes. Le paquet conserve la référence, mais les fichiers du fournisseur ne sont pas copiés.

Préparer le site cible

Importez dans un site qui remplit toutes les conditions ci-dessous. Lorsque le contenu, les langues, la limite de téléversement ou le format pris en charge par la cible ne conviennent pas au paquet, l’analyse signale un bloqueur.

• Un compte administrateur. L’importation s’exécute en tant qu’administrateur connecté ou avec un jeton d’API. Créez l’administrateur de la cible pendant la configuration.
• Un backend de stockage. L’origine comme la cible ont besoin d’un stockage configuré. EmDash y place les fichiers du paquet en attente.
• Aucun contenu. La cible ne doit contenir aucune entrée (y compris les entrées dans la corbeille), révision, média ou dossier de médias, byline ou champ de byline, commentaire, redirection, attribution de terme, relation, enregistrement SEO, section créée dans l’administration, ni collection ou type de bloc créé après la configuration. Un site configuré à partir de n’importe quel template officiel convient. Ce que la configuration a créé constitue l’ossature de configuration : les collections et types de blocs issus du seed, les définitions de taxonomies et leurs termes non attribués, les menus et leurs éléments, les zones de widgets et leurs widgets, ainsi que les sections du thème. Le plan liste cette ossature, et l’importation la supprime une fois que vous avez confirmé le plan.
• Toutes les langues utilisées par le paquet. Ajoutez chacune des langues du paquet à la configuration i18n de la cible. Un site sans configuration i18n n’accepte que en. Les langues sont comparées sans tenir compte de la casse, et l’importation écrit chaque langue avec la casse configurée sur la cible, ce qui est déclaré comme locale_recased.
• Une limite de téléversement suffisante. Chaque fichier média doit tenir dans la maxUploadSize de la cible, qui est de 50 Mio par défaut.
• Version de format 1. La cible doit prendre en charge la version de format du paquet et chaque fonctionnalité requise.

La requête suivante renvoie les versions de format, les fonctionnalités et les limites prises en charge. Son objet portableDomain indique si le site peut recevoir une importation et, dans le cas contraire, pourquoi.

curl https://new.example.com/_emdash/api/admin/transfer/capabilities \
  -H "Authorization: Bearer $EMDASH_TOKEN"

Exporter un site

Un export lit le site par étapes bornées et écrit le paquet dans le stockage du site. Avant la fin d’un export, l’exportateur valide le paquet terminé de la même manière qu’une importation. Lorsqu’une écriture sur le site réussit pendant un export, l’exportateur recommence. Prendre ou renouveler un verrou d’édition sur une entrée ne compte pas comme une écriture. Après trois tentatives, il échoue avec TRANSFER_EXPORT_CONCURRENT_WRITES.

Les fichiers de l’export restent disponibles pendant sept jours après la création de l’export. Passé ce délai, un téléchargement renvoie TRANSFER_EXPIRED.

Exporter depuis l’administration

La section affiche également l’empreinte (digest) du paquet, le nombre d’enregistrements de chaque type et les exports récents du site, chacun avec son propre bouton de téléchargement jusqu’à son expiration.

Download package récupère l’export un fichier à la fois, vérifie la taille et l’empreinte SHA-256 de chaque fichier par rapport au manifeste, puis construit le fichier .emdash dans le navigateur ; cela fonctionne donc sur Cloudflare Workers pour des sites de toute taille. Si un fichier ne correspond pas, le téléchargement s’arrête avec une erreur. Chrome, Edge et les autres navigateurs basés sur Chromium écrivent le fichier directement sur le disque. Les autres navigateurs gardent l’intégralité du paquet en mémoire jusqu’à la fin du téléchargement ; pour un export de plus de 500 Mo environ, la page recommande un navigateur basé sur Chromium ou la CLI.

Download as one file demande plutôt au serveur l’archive en une seule réponse. Cette option convient aux petits sites. Sur Cloudflare Workers, un site volumineux peut dépasser les limites d’une seule requête.

Exporter avec la CLI

Connectez-vous au site d’origine, puis exportez-le dans un fichier de paquet :

npx emdash login --url https://example.com
npx emdash site export --url https://example.com --output site.emdash

La commande mène l’export à son terme, télécharge le paquet fichier par fichier, vérifie la taille et l’empreinte de chaque fichier et écrit site.emdash. Ajoutez --no-comments pour exclure les commentaires et les réactions. Si la commande est interrompue, relancez-la avec les mêmes options pour reprendre le même export. Consultez la référence de emdash site export.

Exporter avec l’API REST

Chaque appel à advance exécute une étape et renvoie nextRequestInMs, le délai avant l’appel suivant. L’export est terminé lorsque nextRequestInMs vaut null.

Ces exemples utilisent un jeton d’accès personnel doté de la portée transfer:export. Consultez portées de jeton.

Un fichier .emdash est une archive tar non compressée dont la première entrée est manifest.json. L’archive diffuse tous les fichiers en une seule réponse. Sur Cloudflare Workers, un site volumineux peut dépasser les limites d’une seule requête. Téléchargez alors manifest.json depuis exports/{id}/manifest et chaque fichier depuis exports/{id}/files/{path}. Chaque fichier téléchargé est vérifié par rapport à son empreinte enregistrée pendant sa diffusion. Si les octets stockés ont changé après l’export, le téléchargement se termine par une erreur au lieu d’aboutir.

Importer un site

Une importation est créée à partir d’un paquet, analysée pour produire un plan, puis exécutée uniquement après que vous avez confirmé ce plan par son empreinte. Une importation dont l’exécution n’a pas commencé expire 24 heures après sa création.

L’administration, la CLI et l’API REST peuvent exécuter chaque étape. Un agent IA peut analyser et démarrer une importation déjà téléversée, au moyen des outils MCP.

Importer depuis l’administration

La page propose également Cancel import depuis le téléversement jusqu’à la fin de l’importation, et Abandon import après l’échec ou l’annulation d’une importation qui avait commencé à écrire. Les deux demandent une confirmation. Consultez annuler une importation et abandonner une importation incomplète.

Importer avec la CLI

Connectez-vous au site cible, puis analysez le paquet :

npx emdash login --url https://new.example.com
npx emdash site import site.emdash --url https://new.example.com --analyze

La commande vérifie localement l’intégralité du fichier de paquet, le téléverse, l’analyse et affiche le plan avec son empreinte de plan. Elle se termine avec le code 2 lorsque le plan comporte des bloqueurs. Examinez le plan comme décrit dans examiner le plan d’importation.

Pour modifier les décisions du plan, relancez --analyze avec des options de décision. --map-principal associe un principal, par ID ou adresse e-mail, à un utilisateur cible par ID ou adresse e-mail, ou à none. --use-target-title et --use-target-tagline conservent le titre et le slogan de la cible :

npx emdash site import site.emdash --url https://new.example.com --analyze \
  --map-principal editor@example.com=editor@example.com \
  --map-principal 01J8ZQ4Y6T2N0D3VJ5R7K9M1PX=none \
  --use-target-title

Exécutez le plan que vous avez examiné en passant son empreinte :

npx emdash site import site.emdash --url https://new.example.com \
  --plan sha256:3f1c… --confirm

La commande mène l’importation à son terme et affiche le reçu. Si elle est interrompue, poursuivez-la avec emdash site import resume <operation-id>. emdash site import status <operation-id> affiche l’état de l’importation, et emdash site import receipt <operation-id> affiche à nouveau le reçu. Consultez la référence de emdash site import.

Importer avec l’API REST

Le serveur travaille avec les fichiers contenus dans un paquet, et non avec l’archive .emdash. Décompressez d’abord l’archive. Elle contient manifest.json, des fichiers d’index sous index/, des fichiers d’enregistrements sous records/ et des fichiers médias sous media/. Le manifeste fixe la taille et l’empreinte SHA-256 de chaque fichier, de sorte que l’empreinte du paquet identifie l’ensemble du paquet.

Ces exemples utilisent un jeton doté des portées transfer:analyze et transfer:execute.

L’exécution échoue avec TRANSFER_PACKAGE_DIGEST_MISMATCH ou TRANSFER_PLAN_DIGEST_MISMATCH lorsque l’une des empreintes diffère du paquet en attente ou du plan actuel. Lisez le plan actuel depuis imports/{id}/plan, examinez-le à nouveau et réessayez avec ses empreintes.

Associer les auteurs aux utilisateurs cibles

L’analyse liste chaque principal avec son nom d’affichage, son adresse e-mail et le nombre d’enregistrements du paquet qui y font référence. Lorsqu’exactement un utilisateur cible possède la même adresse e-mail, comparée sans tenir compte de la casse, le plan suggère cet utilisateur et y associe le principal par défaut. Les principals sans suggestion commencent sans association.

Pour modifier une association, passez --map-principal à emdash site import --analyze, ou soumettez principalMappings au point de terminaison d’analyse. Chaque association désigne un utilisateur cible ou laisse le principal sans association (none dans la CLI, null dans l’API). EmDash applique chaque association aux auteurs d’entrées, aux auteurs de révisions, aux personnes ayant téléversé les médias, aux liens utilisateur des bylines et aux auteurs de commentaires.

Les références d’un principal sans association sont supprimées. Lorsqu’un auteur sans association avait également une byline liée à son compte, l’importateur crédite explicitement cette byline sur chacune des entrées de l’auteur qui n’a pas de crédit de byline explicite et dont la langue possède la byline de l’auteur. Le crédit de l’auteur reste donc sur la page.

Deux associations produisent un bloqueur principal_conflict :

• un principal possédant plus d’une byline dans la même langue est associé à un utilisateur ; ou
• deux principals ayant tous deux des bylines dans la même langue sont associés au même utilisateur.

Un utilisateur cible ne peut avoir qu’une seule byline par langue. Laissez un principal sans association, ou associez les principals à des utilisateurs différents.

Examiner le plan d’importation

Un plan liste ce que l’importation va créer, les décisions qu’elle va appliquer et trois types de constats :

• Les bloqueurs empêchent l’exécution. L’exécution renvoie TRANSFER_PLAN_BLOCKED tant que le plan en comporte. Modifiez les associations de principals pour résoudre un principal_conflict. Tout autre bloqueur nécessite une modification du paquet ou de la cible : annulez l’importation, effectuez la modification et créez une nouvelle importation.
• Les avertissements décrivent des problèmes du paquet qui n’arrêtent pas l’importation. Ils sont recopiés dans le reçu.
• Les transformations sont les différences exactes et déclarées entre le site source et le site importé. Les modifications de l’exportateur sont listées en premier, puis celles de l’importation. La vérification applique les transformations de l’importation lorsqu’elle compare le site importé au paquet.

Un plan liste au maximum 500 bloqueurs et avertissements. Un avertissement issues_truncated indique combien d’autres ont été trouvés.

Bloqueurs

L’importateur écrit directement les enregistrements ; l’analyse applique donc les mêmes contrôles que l’API d’administration lors de l’enregistrement de ces données. Chacune de ces valeurs est une value_constraint_violation :

• une valeur d’entrée qui ne tient pas dans la colonne de son champ, un champ obligatoire sans valeur, ou une valeur pour un champ que la collection ne possède pas ;
• une redirection dont la source ou la destination n’est pas un chemin du site, dont le type n’est pas pris en charge, dont le motif source est invalide, ou dont la destination utilise un paramètre que la source ne capture pas ;
• un site web de byline qui n’est pas une URL http ou https, une valeur de champ de byline qui ne correspond pas au type ou aux choix de son champ, ou un champ de byline comportant plus de choix qu’un site n’en prend en charge ;
• un motif d’URL de collection invalide ;
• un type de bloc avec un slug réservé, un libellé vide ou de plus de 200 caractères, ou des définitions de champs que l’éditeur de types de blocs refuserait ;
• une URL canonique SEO qui n’est ni une URL http ou https ni un chemin du site ; et
• une URL d’élément de menu avec un schéma que les menus n’autorisent pas.

Avertissements

Transformations

L’exportateur déclare les modifications qu’il a apportées aux données du site source. Chacune de ces transformations comporte un type d’enregistrement et un nombre :

L’importation déclare ses propres modifications :

Exécuter l’importation

L’exécution parcourt ces phases dans l’ordre :

1. Réserver la cible et vérifier à nouveau qu’elle est vide.
2. Supprimer l’ossature de configuration listée dans le plan.
3. Créer les types de blocs, les collections, les champs, les définitions de taxonomies, les définitions de relations et les champs de byline.
4. Copier les fichiers médias dans le stockage de la cible et créer les enregistrements de médias.
5. Écrire les termes et les bylines.
6. Écrire les révisions et les entrées.
7. Écrire les attributions de termes, les crédits de byline, les références de contenu et les enregistrements SEO.
8. Écrire les menus, widgets, sections, redirections, commentaires, réactions et paramètres.
9. Reconstruire les index de recherche et les caches, et mettre en file d’attente la réindexation de l’utilisation des médias.
10. Vérifier le résultat.

Chaque appel à advance exécute une étape bornée, qui tient dans les limites de requête de Cloudflare Workers sur D1. La progression est stockée sur le serveur. Une requête interrompue perd au plus l’étape en cours, et chaque écriture est idempotente : relancer une étape ne duplique donc aucun enregistrement.

Pendant qu’une autre requête exécute une étape, ou lorsqu’une autre requête reprend l’opération pendant une étape, advance renvoie l’opération avec un nextRequestInMs court. Une erreur de stockage ou de base de données est réessayée : l’opération enregistre l’erreur, et nextRequestInMs augmente à chaque échec consécutif. Après des échecs répétés sans progression, l’importation échoue.

Les écritures sont bloquées pendant une importation

De la première étape d’exécution jusqu’à la fin de l’importation, EmDash rejette les requêtes d’écriture adressées à son API avec 503 TRANSFER_IMPORT_IN_PROGRESS. Cela concerne l’administration, l’API REST, les routes de plugins, les soumissions publiques de commentaires, la publication planifiée et les écritures de contenu par les plugins. La connexion, la gestion des utilisateurs et des jetons d’API, les verrous d’édition des entrées et l’API de transfert elle-même restent disponibles. Les requêtes de lecture ne sont pas bloquées.

Les outils MCP d’écriture, y compris les outils MCP des plugins, échouent avec TRANSFER_IMPORT_IN_PROGRESS dans l’erreur d’outil habituelle. Les outils MCP en lecture seule et les outils de transfert site_* continuent de fonctionner, de sorte qu’une importation démarrée via MCP peut être reprise, inspectée et terminée via MCP.

Reprendre après une interruption

La page d’administration ne fait avancer une importation que tant qu’elle est ouverte. Pour reprendre, rouvrez Settings → Transfer, exécutez emdash site import resume <operation-id> ou appelez à nouveau advance pour la même opération. Le serveur reprend à partir de la dernière étape terminée. Si la requête interrompue détenait encore l’opération, l’appel suivant attend l’expiration de cette détention, cinq minutes au maximum.

Une importation échouée ou annulée ne peut pas être reprise.

Annuler une importation

Sélectionnez Cancel import dans Settings → Transfer, exécutez emdash site import cancel <operation-id> ou envoyez POST imports/{id}/cancel. Une étape en cours s’arrête après son lot actuel. L’annulation ne supprime pas les enregistrements déjà écrits.

Abandonner une importation incomplète

Une importation échouée ou annulée qui avait commencé à écrire continue de bloquer les écritures, afin que le site incomplet ne puisse pas être modifié par erreur. Pour lever le blocage, sélectionnez Abandon import dans Settings → Transfer, exécutez emdash site import abandon <operation-id> ou envoyez POST imports/{id}/abandon. L’abandon conserve les données importées.

Après un abandon, le site n’est plus vide et ne peut donc pas recevoir une autre importation. Importez plutôt dans un site nouvellement configuré.

Une importation échouée ou annulée qui n’avait jamais commencé à écrire ne bloque pas les écritures et n’a pas besoin d’être abandonnée.

Vérifier le résultat

La vérification relit chaque enregistrement importé avec le même code que celui de l’exportateur, applique les transformations déclarées du plan aux enregistrements du paquet et compare les deux. Elle vérifie aussi le nombre d’enregistrements de chaque type et télécharge à nouveau chaque fichier média importé pour en vérifier l’empreinte. Toute différence fait échouer l’importation avec TRANSFER_VERIFICATION_FAILED. Le errorDetail de l’opération liste jusqu’à 50 de ces différences.

Une importation réussie produit un reçu :

{
	"operationId": "01J8ZR2C4S6D8F0G2H4J6K8M0N",
	"packageDigest": "sha256:…",
	"planDigest": "sha256:…",
	"targetSiteId": "01J8ZR0A2B4C6D8E0F2G4H6J8K",
	"originSiteId": "01J1A3C5E7G9J1L3N5Q7S9U1W3",
	"formatVersion": "1",
	"importerEmDashVersion": "0.38.0",
	"completedAt": "2026-09-23T10:15:00.000Z",
	"logicalDigest": "sha256:…",
	"counts": { "entry": 412, "media": 96 },
	"warnings": [],
	"verification": "verified",
	"receiptDigest": "sha256:…"
}

Un reçu atteste que le site cible identifié par targetSiteId contenait exactement le contenu du paquet identifié par packageDigest, après application du plan identifié par planDigest, au moment où la vérification s’est terminée. Le logicalDigest résume les enregistrements vérifiés.

receiptDigest est l’empreinte SHA-256 du JSON canonique du reçu, sans la propriété receiptDigest. Elle permet de détecter un reçu modifié après son émission. Un reçu n’est pas signé et ne prouve donc pas quel serveur l’a émis. Récupérez le reçu depuis la cible via une connexion authentifiée lorsque cela compte.

Un reçu décrit le site au moment où la vérification s’est terminée. Il ne dit rien des modifications ultérieures.

Passer d’une base de données à une autre

Un paquet ne dépend pas de la base de données de l’origine. Exportez depuis SQLite, PostgreSQL ou D1 et importez dans n’importe laquelle d’entre elles. Prévoyez les différences suivantes lorsque la cible utilise PostgreSQL :

• PostgreSQL stocke les entiers sur 32 bits. Un entier en dehors de cette plage est un bloqueur integer_out_of_range.
• PostgreSQL stocke les champs number et les points focaux des médias sous forme de nombres à virgule flottante sur 32 bits. Les valeurs qui changent sont déclarées comme float4_rounded, et la vérification compare les valeurs arrondies.
• La recherche plein texte n’est disponible que sur SQLite et D1. Les collections dont la recherche est activée sont importées avec la recherche désactivée et déclarées comme search_unsupported.

L’importateur écrit les médias dans le backend de stockage de la cible sous de nouvelles clés de stockage et réécrit en conséquence les références aux médias dans le contenu, les paramètres et les enregistrements SEO. Une référence à un fichier média que l’origine ne possède pas est exportée sans modification et déclarée comme unknown_storage_key.

Sécurité

• Traitez un paquet comme sensible. Il contient tout le contenu, y compris les brouillons et la corbeille, ainsi que les adresses e-mail des auteurs et des commentateurs. Tenez-le à l’écart des buckets publics et des dossiers partagés, et supprimez les copies dont vous n’avez plus besoin.
• Traitez un paquet comme une entrée non fiable. L’importation vérifie les chemins, les tailles, les empreintes, les schémas d’enregistrements, les références et les limites avant d’écrire. Elle n’exécute jamais de code ni de SQL provenant d’un paquet et ne récupère jamais d’URL qu’il contient.
• Accordez l’accès au transfert de manière réfléchie. Le transfert nécessite le rôle d’administrateur. Un jeton doté de la portée admin peut exécuter toutes les actions de transfert ; ne donnez donc au jeton d’un agent que la portée de transfert dont il a besoin.
• Examinez le journal d’audit. EmDash consigne les actions de transfert dans le journal d’audit du site : transfer_export_create, transfer_import_create, transfer_import_execute, transfer_import_cancel, transfer_import_abandon, transfer_import_complete, transfer_import_fail, transfer_approval_approve et transfer_approval_deny. Chaque entrée indique l’utilisateur à l’origine de l’action et l’opération ou l’approbation concernée (type de ressource transfer_operation ou transfer_approval). Ses détails ne contiennent que des ID, des empreintes, des nombres d’enregistrements et des codes d’erreur, jamais le contenu du paquet. De même, les détails des erreurs de transfert n’incluent jamais le contenu du paquet.
• Gardez la zone d’attente privée. EmDash place les fichiers du paquet sous le préfixe transfers/ de votre bucket de stockage et refuse de servir ce préfixe via sa route de médias. Si le bucket dispose d’un domaine public, limitez-le aux médias, comme pour les sauvegardes. Les fichiers en attente sont supprimés à la fin ou à l’expiration d’une opération.

Portées de jeton

Le transfert utilise trois portées de jeton d’API :

La portée admin inclut les trois ; le jeton enregistré par emdash login peut donc exécuter tout transfert. Chaque portée de transfert n’accorde que ses propres actions, et seul un administrateur peut en émettre une. Utilisez-les pour donner à un jeton un accès plus restreint que admin, par exemple à un agent qui peut analyser des paquets mais ni exporter ni importer. Consultez la référence des portées.

Approbations pour les agents

Les agents IA pilotent les transferts au moyen des outils MCP site_*. Ces outils démarrent les opérations, les font avancer et en rendent compte. Ils ne transportent jamais les octets du paquet : l’utilisateur d’un agent télécharge donc les exports et téléverse les paquets avec la CLI ou l’API REST. Chaque outil nécessite le rôle Admin.

Un client MCP dont le jeton ne possède ni admin ni la portée de transfert correspondante, comme un agent qui n’a reçu que transfer:analyze, ne peut pas démarrer seul un export ou une importation. Son appel à site_export_start ou site_import_start crée une demande d’approbation en attente et échoue avec TRANSFER_APPROVAL_REQUIRED et l’ID de l’approbation. Un administrateur approuve ou refuse la demande sous Approval requests dans Settings → Transfer, qui liste chaque demande en attente avec son demandeur, son action et son heure d’expiration. Les points de terminaison réservés aux sessions POST /_emdash/api/admin/transfer/approvals/{id}/approve et …/deny font de même. Les jetons d’API ne peuvent pas approuver de demandes. Le client répète ensuite l’appel avec l’ID de l’approbation. Les approbations ne s’appliquent qu’à ces outils MCP ; l’API REST n’a pas de paramètre d’approbation.

Une approbation accorde un appel à l’utilisateur qui l’a demandée, depuis le même jeton et avec les mêmes arguments. Une approbation d’export est liée aux options d’export. Une approbation d’importation est liée à l’opération et aux deux empreintes ; un plan modifié nécessite donc une nouvelle approbation. Une demande en attente expire au bout de 15 minutes, et une demande approuvée 15 minutes après l’approbation. La nouvelle tentative qui démarre l’opération la consomme ; si l’opération ne parvient pas à démarrer, la même approbation peut être réessayée jusqu’à son expiration. Le même utilisateur et le même jeton peuvent ensuite consulter et faire avancer cette opération sans la portée.

N’accordez transfer:export, transfer:execute ou admin au jeton d’un agent que lorsque l’agent doit exécuter des transferts sans qu’une personne n’approuve chacun d’eux.

Limites

Le point de terminaison capabilities indique les valeurs que le site applique.

Pour les hébergeurs

Un plan de contrôle d’hébergement peut faire passer le site d’un client en production uniquement avec l’API REST :

Gardez la cible inaccessible tant que l’étape 4 n’a pas réussi. EmDash ne masque pas aux visiteurs un site partiellement importé.

Dépannage

Les erreurs de transfert utilisent des codes stables. Le statut HTTP figure à côté de chaque code.