Importazione di contenuti

EmDash importa i contenuti di WordPress tramite la pagina Import from WordPress all’indirizzo /_emdash/admin/import/wordpress. L’importatore può analizzare un file WordPress eXtended RSS (WXR) o collegarsi a un sito che esegue il plugin EmDash Exporter.

Fonti di importazione

Il registro delle fonti contiene tre fonti WordPress:

Non esiste una fonte di importazione OAuth wordpress-com. Un sito WordPress.com deve usare un’esportazione WXR o una connessione EmDash Exporter compatibile.

Importare un file WXR

Usa WXR quando WordPress può esportare i contenuti che ti servono e non è possibile installare EmDash Exporter.

L’XML contiene i metadati degli allegati e gli URL di origine, non i byte dei media. Mantieni WordPress raggiungibile finché la copia facoltativa dei media non è terminata.

Collegare EmDash Exporter

Usa l’exporter quando controlli il sito WordPress e ti servono dati autenticati come bozze o impostazioni supportate. Commenti, menu, logo, favicon e la pagina Tools → EmDash Migration che genera una chiave di migrazione richiedono l’exporter 1.2.0 o successivo. Qualsiasi versione dell’exporter può collegarsi con un nome utente WordPress e una password per le applicazioni. L’exporter invia i dati tramite i propri endpoint API emdash/v1; non concede a EmDash accesso diretto al database.

Flusso di importazione dell’amministrazione

L’amministrazione esegue queste fasi:

1. Collegare. Carica un file WXR, incolla una chiave di migrazione di EmDash Exporter oppure inserisci l’URL di un sito.
2. Analizzare. Legge tipi di contenuto, campi obbligatori, autori, allegati e compatibilità dello schema.
3. Esaminare. Seleziona tipi di contenuto, associazioni alle collezioni, autori ed extra supportati.
4. Preparare. Crea le collezioni e i campi mancanti. I campi esistenti con tipi incompatibili bloccano quella associazione.
5. Importare. Converte e crea i contenuti. Il percorso dell’exporter usa richieste di dimensione limitata per contenuti, commenti e finalizzazione.
6. Copiare i media. Scarica gli allegati WXR selezionati nello storage di EmDash e riscrive gli URL corrispondenti.

Il percorso WXR può importare articoli, pagine, tipi di contenuto personalizzati, tassonomie, blocchi riutilizzabili, autori o byline ospite e i media elencati nell’esportazione. Il percorso dell’exporter può inoltre recuperare dall’API WordPress attiva alcune impostazioni del sito e i valori SEO supportati e, con l’exporter 1.2.0 o successivo, anche commenti, menu, logo e favicon.

Comprendere l’analisi

Per ogni tipo di contenuto rilevato, la schermata di revisione mostra la collezione suggerita e uno dei quattro stati dello schema:

Il passaggio di preparazione è additivo. Non cambia il tipo di un campo esistente per adattarlo a un’importazione.

Associazione degli stati

Le route dei contenuti memorizzano due stati da un’importazione WordPress:

L’importatore non conserva la semantica WordPress di in attesa, privato, programmato o cestino. Controlla queste voci prima di pubblicarle in EmDash.

Contenuti e identificatori

Le fonti WXR ed exporter convertono il markup di Gutenberg in Portable Text. Associano post a posts, page a pages e i tipi di contenuto personalizzati noti a slug di collezione. I tipi di contenuto interni di WordPress sono esclusi. I blocchi riutilizzabili (wp_block) vengono gestiti come sezioni di EmDash anziché come voci ordinarie.

Per una voce importata:

• Lo slug dell’articolo WordPress diventa lo slug di EmDash, quando disponibile.
• EmDash genera un proprio ID di database.
• Le associazioni degli autori collegano un utente EmDash. Un autore WordPress non associato può diventare una byline ospite riutilizzabile.
• Gli ID di WordPress vengono usati in modo transitorio per risolvere relazioni come menu, commenti, immagini in evidenza e traduzioni. Non sono l’identità persistente usata per rilevare una voce WXR esistente.

Le riesecuzioni WXR con skipExisting associano una voce esistente per collezione, slug e locale. Uno slug modificato può quindi creare un’altra voce. Il percorso dell’exporter usa lo stesso controllo su slug e locale e ricostruisce la propria mappa delle relazioni per ID WordPress a partire dalle voci che salta.

Copia e deduplicazione dei media

La fase dei media scarica l’URL di ogni allegato, calcola un hash SHA-1 dei byte scaricati e cerca una riga di media esistente con quell’hash del contenuto. Byte identici riutilizzano il record di media esistente anche quando gli URL di WordPress sono diversi.

L’hash viene memorizzato con il prefisso sha1:. È una chiave di deduplicazione, non una firma di sicurezza. Due URL non vengono considerati duplicati solo perché i loro nomi di file coincidono.

Dopo aver copiato i media, l’importatore riscrive gli URL corrispondenti nei campi Portable Text, testo, stringa, immagine e file. Mantieni online l’origine WordPress finché download e pagine riscritte non sono stati verificati.

Comportamento dei nuovi tentativi

L’amministrazione non memorizza un token di ripresa duraturo per un’importazione WXR. Se una richiesta fallisce:

• Riesegui l’analisi e l’importazione con skip existing attivo.
• Le voci esistenti vengono saltate per collezione, slug e locale.
• Rieseguire i media è sicuro per i file già memorizzati, perché i download identici byte per byte riutilizzano l’hash del contenuto.
• Controlla le modifiche parziali allo schema e le voci con slug modificato prima di riprovare.

Il flusso dell’exporter è suddiviso in blocchi per rispettare i limiti dei Worker. Il browser trasporta i cursori e le mappe delle relazioni da WordPress a EmDash tra una richiesta e l’altra. Se il browser perde quello stato, riavvia l’importazione; le voci saltate ricostruiscono la mappa delle relazioni man mano che le pagine di contenuti vengono elaborate.

La CLI separata emdash import wordpress scrive file JSON convertiti in una directory di output. La sua opzione --resume legge .wp-migration-progress.json e salta gli ID di articoli e allegati WordPress già registrati lì. Quel flusso di conversione in file non è l’importazione nel database dell’amministrazione e non rende riprendibili le richieste dell’amministrazione.

Contratti dell’API di amministrazione

Questi endpoint alimentano la pagina di amministrazione autenticata. Richiedono una sessione amministratore con import:execute e l’header X-EmDash-Request: 1. Le risposte di successo normalmente usano l’involucro { "success": true, "data": ... }; gli errori usano { "success": false, "error": { "code", "message" } }.

Verificare un URL

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

Il suo valore data è { success: true, result }. result contiene url, isWordPress, bestMatch e allMatches. Una semplice corrispondenza con la REST di WordPress consiglia un caricamento WXR; non abilita l’importazione REST diretta.

Analizzare un file WXR

POST /_emdash/api/import/wordpress/analyze accetta multipart/form-data con una parte file. Il suo valore data contiene il sito, l’analisi dei tipi di contenuto, il riepilogo degli allegati, il riepilogo degli autori, i conteggi delle tassonomie e i suggerimenti per i campi personalizzati.

Preparare lo schema

POST /_emdash/api/import/wordpress/prepare accetta questa forma di JSON:

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

Il suo valore data contiene success, collectionsCreated, fieldsCreated e gli errors per collezione.

Eseguire un’importazione WXR

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

• file: il file WXR.
• config: una stringa JSON contenente postTypeMappings, skipExisting, facoltativamente authorMappings, facoltativamente importSections e un locale facoltativo valido per l’intera importazione.

Il suo valore data contiene success, imported, skipped, errors, byCollection e riepiloghi facoltativi di sezioni e tassonomie.

Copiare i media

POST /_emdash/api/import/wordpress/media accetta il JSON { "attachments": [...], "stream": true }. Lo streaming è l’impostazione predefinita. Una risposta in streaming è JSON delimitato da a capo, con record progress seguiti da un record result; non usa il normale involucro dell’API. Imposta stream su false per ricevere il normale involucro attorno a { imported, failed, urlMap }.

Riscrivere gli URL dei media

POST /_emdash/api/import/wordpress/rewrite-urls accetta il JSON { "urlMap": { "old": "new" }, "collections": ["posts"] }. L’elenco facoltativo di collezioni limita la riscrittura. Il suo valore data contiene i conteggi delle voci aggiornate e degli URL riscritti, più gli errori.

Usare l’API dell’exporter

POST /_emdash/api/import/wordpress-plugin/analyze accetta il JSON { "url", "token" }, dove token è un valore di autenticazione Basic codificato in Base64 per un utente WordPress e una password per le applicazioni. Il suo valore data è { success: true, analysis }.

POST /_emdash/api/import/wordpress-plugin/execute accetta il JSON con url, token e config. L’amministrazione fornisce anche una phase (content, comments o finalize). Ogni risposta contiene done, un cursor successivo facoltativo, un result parziale e un oggetto chunk con eventuali idMap, translationGroups o commentRoots aggiornati. L’amministrazione unisce i valori di chunk e invia le mappe accumulate con la richiesta successiva.

Risoluzione dei problemi

Il sito viene rilevato ma non può essere importato direttamente

Un risultato wordpress-rest è solo una verifica. Carica un file WXR oppure installa EmDash Exporter e verifica di nuovo il sito.

Un tipo di contenuto è incompatibile

Espandi il tipo di contenuto nella schermata di revisione per trovare il campo in conflitto. Cambia la collezione di destinazione oppure riconcilia quel campo in Content Types. L’importatore non sostituisce il tipo di un campo esistente.

Alcuni media non sono stati scaricati

Il risultato finale dei media elenca gli URL di origine non riusciti. Conferma che ogni URL sia pubblico, esista ancora e non reindirizzi a un indirizzo di rete privata. Ripeti il passaggio dei media dopo aver corretto l’accesso; i file già completati e identici byte per byte verranno riutilizzati.

Prossimi passi

• Migrare da WordPress per la procedura operativa.
• Portare un tema WordPress dopo l’importazione dei contenuti.
• Portare plugin WordPress quando il sito dipende da comportamenti personalizzati.