Importação de Conteúdo

O EmDash importa conteúdo do WordPress pela página Import from WordPress, em /_emdash/admin/import/wordpress. O importador pode analisar um arquivo WordPress eXtended RSS (WXR) ou se conectar a um site que executa o plugin EmDash Exporter.

Fontes de importação

O registro de fontes contém três fontes do WordPress:

Não existe uma fonte de importação OAuth wordpress-com. Um site WordPress.com precisa usar uma exportação WXR ou uma conexão compatível do EmDash Exporter.

Importar um arquivo WXR

Use o WXR quando o WordPress puder exportar o conteúdo de que você precisa e o EmDash Exporter não puder ser instalado.

O XML contém os metadados dos anexos e as URLs de origem, não os bytes da mídia. Mantenha o WordPress acessível até que a cópia opcional da mídia seja concluída.

Conectar o EmDash Exporter

Use o exporter quando você controla o site WordPress e precisa de dados autenticados, como rascunhos, comentários, menus ou configurações compatíveis. Gere uma chave de migração em Tools → EmDash Migration ou conecte-se com um nome de usuário do WordPress e uma senha de aplicativo. O exporter envia os dados pelos seus endpoints de API emdash/v1; ele não concede ao EmDash acesso direto ao banco de dados.

Fluxo de importação do administrador

O administrador executa estas etapas:

1. Conectar. Envie um arquivo WXR, cole uma chave de migração do EmDash Exporter ou informe a URL de um site.
2. Analisar. Lê os tipos de post, os campos obrigatórios, os autores, os anexos e a compatibilidade do esquema.
3. Revisar. Selecione os tipos de post, os mapeamentos de coleção, os autores e os extras compatíveis.
4. Preparar. Cria as coleções e os campos que estiverem faltando. Campos existentes com tipos incompatíveis bloqueiam esse mapeamento.
5. Importar. Converte e cria o conteúdo. O caminho do exporter usa requisições de tamanho limitado para conteúdo, comentários e finalização.
6. Copiar mídia. Baixa os anexos WXR selecionados para o armazenamento do EmDash e reescreve as URLs correspondentes.

O caminho WXR pode importar posts, páginas, tipos de post personalizados, taxonomias, blocos reutilizáveis, autores ou bylines de convidado e a mídia listada na exportação. O caminho do exporter também pode buscar, na API ativa do WordPress, comentários, menus, configurações do site selecionadas e valores de SEO compatíveis.

Entender a análise

Para cada tipo de post detectado, a tela de revisão mostra a coleção sugerida e um entre quatro estados do esquema:

A etapa de preparação é aditiva. Ela não altera o tipo de um campo existente para que uma importação se encaixe.

Mapeamento de status

As rotas de conteúdo armazenam dois status de uma importação do WordPress:

O importador não preserva a semântica de pendente, privado, agendado ou lixeira do WordPress. Revise essas entradas antes de publicá-las no EmDash.

Conteúdo e identificadores

As fontes WXR e exporter convertem a marcação do Gutenberg em Portable Text. Elas mapeiam post para posts, page para pages e os tipos de post personalizados conhecidos para slugs de coleção. Os tipos de post internos do WordPress são excluídos. Os blocos reutilizáveis (wp_block) são tratados como seções do EmDash, e não como entradas comuns.

Para uma entrada importada:

• O slug do post do WordPress passa a ser o slug do EmDash, quando disponível.
• O EmDash gera o próprio ID de banco de dados.
• Os mapeamentos de autor associam um usuário do EmDash. Um autor do WordPress sem mapeamento pode se tornar uma byline de convidado reutilizável.
• Os IDs do WordPress são usados de forma transitória para resolver relacionamentos como menus, comentários, imagens destacadas e traduções. Eles não são a identidade persistente usada para detectar uma entrada WXR existente.

As reexecuções de WXR com skipExisting correspondem uma entrada existente por coleção, slug e localidade. Portanto, um slug alterado pode criar outra entrada. O caminho do exporter usa a mesma verificação de slug e localidade e reconstrói o mapa de relacionamentos por ID do WordPress a partir das entradas que ele ignora.

Cópia e deduplicação de mídia

A etapa de mídia baixa a URL de cada anexo, calcula um hash SHA-1 dos bytes baixados e procura uma linha de mídia existente com esse hash de conteúdo. Bytes idênticos reutilizam o registro de mídia existente, mesmo quando as URLs do WordPress são diferentes.

O hash é armazenado com o prefixo sha1:. Ele é uma chave de deduplicação, não uma assinatura de segurança. Duas URLs não são tratadas como duplicadas apenas porque os nomes de arquivo coincidem.

Depois de copiar a mídia, o importador reescreve as URLs correspondentes em campos de Portable Text, texto, string, imagem e arquivo. Mantenha a origem do WordPress online até que os downloads e as páginas reescritas tenham sido verificados.

Comportamento de novas tentativas

O administrador não armazena um token de retomada durável para uma importação WXR. Se uma requisição falhar:

• Execute novamente a análise e a importação com skip existing ativado.
• As entradas existentes são ignoradas por coleção, slug e localidade.
• Executar a mídia novamente é seguro para arquivos já armazenados, porque downloads idênticos byte a byte reutilizam o hash de conteúdo.
• Inspecione as alterações parciais do esquema e as entradas com slugs alterados antes de tentar novamente.

O fluxo do exporter é dividido em blocos para caber nos limites do Worker. O navegador transporta os cursores e os mapas de relacionamento do WordPress para o EmDash entre as requisições. Se o navegador perder esse estado, reinicie a importação; as entradas ignoradas reconstroem o mapa de relacionamentos à medida que as páginas de conteúdo são processadas.

A CLI separada emdash import wordpress grava arquivos JSON convertidos em um diretório de saída. A opção --resume lê .wp-migration-progress.json e ignora os IDs de posts e anexos do WordPress já registrados ali. Esse fluxo de conversão em arquivos não é a importação para o banco de dados feita pelo administrador e não torna as requisições do administrador retomáveis.

Contratos da API do administrador

Esses endpoints alimentam a página autenticada do administrador. Eles exigem uma sessão de administrador com import:execute e o cabeçalho X-EmDash-Request: 1. As respostas de sucesso normalmente usam o envelope { "success": true, "data": ... }; os erros usam { "success": false, "error": { "code", "message" } }.

Sondar uma URL

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

O valor de data é { success: true, result }. result contém url, isWordPress, bestMatch e allMatches. Uma correspondência simples com a REST do WordPress recomenda o envio de um WXR; ela não habilita a importação REST direta.

Analisar um arquivo WXR

POST /_emdash/api/import/wordpress/analyze aceita multipart/form-data com uma parte file. O valor de data contém o site, a análise dos tipos de post, o resumo dos anexos, o resumo dos autores, as contagens de taxonomias e as sugestões de campos personalizados.

Preparar o esquema

POST /_emdash/api/import/wordpress/prepare aceita este formato de JSON:

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

O valor de data contém success, collectionsCreated, fieldsCreated e errors por coleção.

Executar uma importação WXR

POST /_emdash/api/import/wordpress/execute aceita multipart/form-data com:

• file: o arquivo WXR.
• config: uma string JSON contendo postTypeMappings, skipExisting, opcionalmente authorMappings, opcionalmente importSections e um locale opcional válido para toda a importação.

O valor de data contém success, imported, skipped, errors, byCollection e resumos opcionais de seções e taxonomias.

Copiar mídia

POST /_emdash/api/import/wordpress/media aceita o JSON { "attachments": [...], "stream": true }. O streaming é o padrão. Uma resposta em streaming é JSON delimitado por quebras de linha, com registros progress seguidos de um registro result; ela não usa o envelope normal da API. Defina stream como false para receber o envelope normal em volta de { imported, failed, urlMap }.

Reescrever as URLs de mídia

POST /_emdash/api/import/wordpress/rewrite-urls aceita o JSON { "urlMap": { "old": "new" }, "collections": ["posts"] }. A lista opcional de coleções limita a reescrita. O valor de data contém as contagens de entradas atualizadas e de URLs reescritas, além dos erros.

Usar a API do exporter

POST /_emdash/api/import/wordpress-plugin/analyze aceita o JSON { "url", "token" }, em que token é um valor de autenticação Basic codificado em Base64 para um usuário do WordPress e uma senha de aplicativo. O valor de data é { success: true, analysis }.

POST /_emdash/api/import/wordpress-plugin/execute aceita o JSON com url, token e config. O administrador também fornece uma phase (content, comments ou finalize). Cada resposta contém done, um próximo cursor opcional, um result parcial e um objeto chunk com eventuais idMap, translationGroups ou commentRoots atualizados. O administrador mescla os valores de chunk e envia os mapas acumulados com a próxima requisição.

Solução de problemas

O site é detectado, mas não pode ser importado diretamente

Um resultado wordpress-rest é apenas uma sondagem. Envie um arquivo WXR ou instale o EmDash Exporter e sonde o site novamente.

Um tipo de post é incompatível

Expanda o tipo de post na tela de revisão para encontrar o campo em conflito. Altere a coleção de destino ou concilie esse campo em Content Types. O importador não substitui o tipo de um campo existente.

Algumas mídias falharam

O resultado final da mídia lista as URLs de origem que falharam. Confirme que cada URL é pública, ainda existe e não redireciona para um endereço de rede privada. Tente novamente a etapa de mídia depois de corrigir o acesso; os arquivos já concluídos e idênticos byte a byte serão reutilizados.

Próximos passos

• Migrar do WordPress para o procedimento do operador.
• Portar um tema WordPress depois que o conteúdo for importado.
• Portar plugins do WordPress quando o site depender de comportamento personalizado.