Importación de contenido

EmDash importa contenido de WordPress a través de la página Import from WordPress en /_emdash/admin/import/wordpress. El importador puede analizar un archivo WordPress eXtended RSS (WXR) o conectarse a un sitio que ejecuta el plugin EmDash Exporter.

Fuentes de importación

El registro de fuentes contiene tres fuentes de WordPress:

No existe una fuente de importación OAuth wordpress-com. Un sitio de WordPress.com debe usar una exportación WXR o una conexión compatible con EmDash Exporter.

Importar un archivo WXR

Usa WXR cuando WordPress pueda exportar el contenido que necesitas y no se pueda instalar EmDash Exporter.

El XML contiene metadatos de los adjuntos y las URL de origen, no los bytes de los medios. Mantén WordPress accesible hasta que haya terminado la copia opcional de los medios.

Conectar el EmDash Exporter

Usa el exportador cuando controles el sitio de WordPress y necesites datos autenticados, como borradores o ajustes compatibles. Los comentarios, los menús, el logotipo, el favicon y la página Tools → EmDash Migration, que genera una clave de migración, requieren el exportador 1.2.0 o posterior. Cualquier versión del exportador puede conectarse con un nombre de usuario de WordPress y una contraseña de aplicación. El exportador envía los datos a través de sus endpoints de API emdash/v1; no concede a EmDash acceso directo a la base de datos.

Flujo de importación del administrador

El administrador realiza estas etapas:

1. Conectar. Sube un archivo WXR, pega una clave de migración de EmDash Exporter o introduce la URL de un sitio.
2. Analizar. Lee los tipos de contenido, los campos obligatorios, los autores, los adjuntos y la compatibilidad del esquema.
3. Revisar. Selecciona los tipos de contenido, las asignaciones de colecciones, los autores y los extras compatibles.
4. Preparar. Crea las colecciones y los campos que falten. Los campos existentes con tipos incompatibles bloquean esa asignación.
5. Importar. Convierte y crea el contenido. La ruta del exportador usa solicitudes acotadas para el contenido, los comentarios y la finalización.
6. Copiar medios. Descarga los adjuntos WXR seleccionados al almacenamiento de EmDash y reescribe las URL coincidentes.

La ruta WXR puede importar entradas, páginas, tipos de contenido personalizados, taxonomías, bloques reutilizables, autores o bylines de invitado, y los medios que figuran en la exportación. La ruta del exportador puede además obtener ajustes del sitio seleccionados y valores SEO compatibles desde la API activa de WordPress y, con el exportador 1.2.0 o posterior, también comentarios, menús, el logotipo y el favicon.

Entender el análisis

Para cada tipo de contenido detectado, la pantalla de revisión muestra la colección sugerida y uno de cuatro estados del esquema:

El paso de preparación es aditivo. No cambia el tipo de un campo existente para que encaje una importación.

Asignación de estados

Las rutas de contenido almacenan dos estados de una importación de WordPress:

El importador no conserva la semántica de pendiente, privado, programado ni papelera de WordPress. Revisa esas entradas antes de publicarlas en EmDash.

Contenido e identificadores

Las fuentes WXR y del exportador convierten el marcado de Gutenberg a Portable Text. Asignan post a posts, page a pages y los tipos de contenido personalizados conocidos a slugs de colección. Los tipos de contenido internos de WordPress se excluyen. Los bloques reutilizables (wp_block) se tratan como secciones de EmDash, no como entradas normales.

Para una entrada importada:

• El slug de la entrada de WordPress pasa a ser el slug de EmDash cuando está disponible.
• EmDash genera su propio ID de base de datos.
• Las asignaciones de autores vinculan un usuario de EmDash. Un autor de WordPress sin asignar puede convertirse en una byline de invitado reutilizable.
• Los ID de WordPress se usan de forma transitoria para resolver relaciones como menús, comentarios, imágenes destacadas y traducciones. No son la identidad persistente que se usa para detectar una entrada WXR existente.

Las repeticiones de WXR con skipExisting emparejan una entrada existente por colección, slug y configuración regional. Por tanto, un slug modificado puede crear otra entrada. La ruta del exportador usa la misma comprobación de slug y configuración regional, y reconstruye su mapa de relaciones por ID de WordPress a partir de las entradas que omite.

Copia y deduplicación de medios

La etapa de medios descarga la URL de cada adjunto, calcula un hash SHA-1 de los bytes descargados y busca una fila de medios existente con ese hash de contenido. Los bytes idénticos reutilizan el registro de medios existente aunque las URL de WordPress sean distintas.

El hash se almacena con el prefijo sha1:. Es una clave de deduplicación, no una firma de seguridad. Dos URL no se tratan como duplicadas solo porque coincidan sus nombres de archivo.

Después de copiar los medios, el importador reescribe las URL coincidentes en los campos de Portable Text, texto, cadena, imagen y archivo. Mantén en línea el origen de WordPress hasta que se hayan verificado las descargas y las páginas reescritas.

Comportamiento de los reintentos

El administrador no almacena un token de reanudación duradero para una importación WXR. Si una solicitud falla:

• Vuelve a ejecutar el análisis y la importación con skip existing activado.
• Las entradas existentes se omiten por colección, slug y configuración regional.
• Volver a ejecutar los medios es seguro para los archivos ya almacenados, porque las descargas idénticas byte a byte reutilizan el hash de contenido.
• Inspecciona los cambios parciales del esquema y las entradas con slugs modificados antes de reintentar.

El flujo del exportador se divide en fragmentos para ajustarse a los límites de Worker. El navegador transporta los cursores y los mapas de relaciones de WordPress a EmDash entre solicitudes. Si el navegador pierde ese estado, reinicia la importación; las entradas omitidas reconstruyen el mapa de relaciones a medida que se procesan las páginas de contenido.

La CLI independiente emdash import wordpress escribe archivos JSON convertidos en un directorio de salida. Su opción --resume lee .wp-migration-progress.json y omite los ID de entradas y adjuntos de WordPress que ya figuran allí. Ese flujo de conversión a archivos no es la importación a la base de datos desde el administrador y no hace que las solicitudes del administrador se puedan reanudar.

Contratos de la API del administrador

Estos endpoints alimentan la página autenticada del administrador. Requieren una sesión de administrador con import:execute y el encabezado X-EmDash-Request: 1. Las respuestas correctas normalmente usan la envoltura { "success": true, "data": ... }; los errores usan { "success": false, "error": { "code", "message" } }.

Sondear una URL

POST /_emdash/api/import/probe acepta JSON { "url": "https://example.com" }.

Su valor data es { success: true, result }. result contiene url, isWordPress, bestMatch y allMatches. Una coincidencia simple con la REST de WordPress recomienda subir un archivo WXR; no habilita la importación directa por REST.

Analizar un archivo WXR

POST /_emdash/api/import/wordpress/analyze acepta multipart/form-data con una parte file. Su valor data contiene el sitio, el análisis de tipos de contenido, el resumen de adjuntos, el resumen de autores, los recuentos de taxonomías y las sugerencias de campos personalizados.

Preparar el esquema

POST /_emdash/api/import/wordpress/prepare acepta esta forma de JSON:

{
  "postTypes": [
    {
      "name": "post",
      "collection": "posts",
      "fields": [
        {
          "slug": "title",
          "label": "Title",
          "type": "string",
          "required": true,
          "searchable": true
        }
      ]
    }
  ]
}

Su valor data contiene success, collectionsCreated, fieldsCreated y errors por colección.

Ejecutar una importación WXR

POST /_emdash/api/import/wordpress/execute acepta multipart/form-data con:

• file: el archivo WXR.
• config: una cadena JSON que contiene postTypeMappings, skipExisting, opcionalmente authorMappings, opcionalmente importSections y un locale opcional para toda la importación.

Su valor data contiene success, imported, skipped, errors, byCollection y resúmenes opcionales de secciones y taxonomías.

Copiar medios

POST /_emdash/api/import/wordpress/media acepta JSON { "attachments": [...], "stream": true }. El streaming es el valor predeterminado. Una respuesta en streaming es JSON delimitado por saltos de línea con registros progress seguidos de un registro result; no usa la envoltura normal de la API. Establece stream en false para recibir la envoltura normal alrededor de { imported, failed, urlMap }.

Reescribir las URL de medios

POST /_emdash/api/import/wordpress/rewrite-urls acepta JSON { "urlMap": { "old": "new" }, "collections": ["posts"] }. La lista opcional de colecciones limita la reescritura. Su valor data contiene los recuentos de entradas actualizadas y de URL reescritas, además de los errores.

Usar la API del exportador

POST /_emdash/api/import/wordpress-plugin/analyze acepta JSON { "url", "token" }, donde token es un valor de autenticación básica codificado en Base64 para un usuario de WordPress y una contraseña de aplicación. Su valor data es { success: true, analysis }.

POST /_emdash/api/import/wordpress-plugin/execute acepta JSON con url, token y config. El administrador también aporta una phase (content, comments o finalize). Cada respuesta contiene done, un siguiente cursor opcional, un result parcial y un objeto chunk con cualquier idMap, translationGroups o commentRoots actualizado. El administrador combina los valores de chunk y envía los mapas acumulados con la siguiente solicitud.

Solución de problemas

El sitio se detecta pero no se puede importar directamente

Un resultado wordpress-rest es solo un sondeo. Sube un archivo WXR o instala EmDash Exporter y vuelve a sondear el sitio.

Un tipo de contenido es incompatible

Expande el tipo de contenido en la pantalla de revisión para encontrar el campo en conflicto. Cambia la colección de destino o concilia ese campo en Content Types. El importador no reemplaza el tipo de un campo existente.

Algunos medios fallaron

El resultado final de medios enumera las URL de origen que fallaron. Confirma que cada URL sea pública, que siga existiendo y que no redirija a una dirección de red privada. Vuelve a intentar el paso de medios después de corregir el acceso; los archivos ya completados e idénticos byte a byte se reutilizarán.

Próximos pasos

• Migrar desde WordPress para el procedimiento del operador.
• Portar un tema de WordPress una vez importado el contenido.
• Portar plugins de WordPress cuando el sitio dependa de comportamientos personalizados.