콘텐츠 가져오기 | EmDash CMS Everything

EmDash는 /_emdash/admin/import/wordpress의 Import from WordPress 페이지를 통해 WordPress 콘텐츠를 가져옵니다. 가져오기 도구는 WordPress eXtended RSS(WXR) 파일을 분석하거나 EmDash Exporter 플러그인이 실행 중인 사이트에 연결할 수 있습니다.

가져오기 소스

소스 레지스트리에는 세 가지 WordPress 소스가 있습니다.

소스 ID	입력	콘텐츠 가져오기	접근
`wxr`	WordPress 내보내기 `.xml` 파일	예	내보내기에 포함된 데이터
`wordpress-plugin`	사이트 URL과 EmDash Exporter 자격 증명	예	Exporter 엔드포인트(인증이 필요한 콘텐츠 포함)
`wordpress-rest`	공개 사이트 URL	아니요	프로브와 공개 개수만

OAuth 가져오기 소스인 wordpress-com은 없습니다. WordPress.com 사이트는 WXR 내보내기 또는 호환되는 EmDash Exporter 연결을 사용해야 합니다.

WXR 파일 가져오기

WordPress에서 필요한 콘텐츠를 내보낼 수 있고 EmDash Exporter를 설치할 수 없을 때 WXR을 사용하세요.

WordPress에서 Tools → Export를 열고 필요한 콘텐츠를 선택한 다음 XML 파일을 다운로드합니다.
EmDash 관리자 사이드바에서 Import를 선택하고 파일을 업로드합니다.
스키마나 콘텐츠를 만들기 전에 감지된 게시물 유형, 필드, 작성자, 택소노미, 재사용 가능한 블록, 첨부 파일 URL을 검토합니다.

XML에는 첨부 파일 메타데이터와 원본 URL이 들어 있으며, 미디어 바이트 데이터는 들어 있지 않습니다. 선택 사항인 미디어 복사가 끝날 때까지 WordPress에 접근할 수 있는 상태를 유지하세요.

EmDash Exporter 연결

WordPress 사이트를 직접 관리하며 초안이나 지원되는 설정 같은 인증이 필요한 데이터가 필요할 때 Exporter를 사용하세요. 댓글, 메뉴, 로고, 파비콘, 그리고 마이그레이션 키를 생성하는 Tools → EmDash Migration 페이지에는 Exporter 1.2.0 이상이 필요합니다. 어떤 버전의 Exporter든 WordPress 사용자 이름과 애플리케이션 비밀번호로 연결할 수 있습니다. Exporter는 emdash/v1 API 엔드포인트를 통해 데이터를 전송하며, EmDash에 데이터베이스 직접 접근 권한을 주지 않습니다.

관리자 가져오기 흐름

관리자는 다음 단계를 수행합니다.

연결. WXR 파일을 업로드하거나, EmDash Exporter 마이그레이션 키를 붙여 넣거나, 사이트 URL을 입력합니다.
분석. 게시물 유형, 필수 필드, 작성자, 첨부 파일, 스키마 호환성을 읽습니다.
검토. 게시물 유형, 컬렉션 매핑, 작성자, 지원되는 추가 항목을 선택합니다.
준비. 누락된 컬렉션과 필드를 만듭니다. 유형이 호환되지 않는 기존 필드가 있으면 해당 매핑이 차단됩니다.
가져오기. 콘텐츠를 변환하고 만듭니다. Exporter 경로는 콘텐츠, 댓글, 마무리 단계마다 크기가 제한된 요청을 사용합니다.
미디어 복사. 선택한 WXR 첨부 파일을 EmDash 스토리지로 다운로드하고 일치하는 URL을 다시 작성합니다.

WXR 경로는 게시물, 페이지, 사용자 정의 게시물 유형, 택소노미, 재사용 가능한 블록, 작성자 또는 게스트 byline, 내보내기에 나열된 미디어를 가져올 수 있습니다. Exporter 경로는 이에 더해 실제 운영 중인 WordPress API에서 선택한 사이트 설정과 지원되는 SEO 값을 가져올 수 있으며, Exporter 1.2.0 이상에서는 댓글, 메뉴, 로고, 파비콘도 가져올 수 있습니다.

분석 결과 이해하기

감지된 게시물 유형마다 검토 화면에는 제안된 컬렉션과 네 가지 스키마 상태 중 하나가 표시됩니다.

상태	의미
Ready	컬렉션과 필수 필드의 유형이 이미 호환됨
New collection	준비 단계에서 컬렉션과 필수 필드를 만듦
Add fields	컬렉션이 있으며, 준비 단계에서 누락된 필드를 추가함
Incompatible	기존 필드의 유형이 다름. 해당 게시물 유형을 가져오기 전에 매핑이나 스키마를 수정해야 함

준비 단계는 추가만 수행합니다. 가져오기에 맞추기 위해 기존 필드의 유형을 변경하지 않습니다.

상태 매핑

콘텐츠 라우트는 WordPress 가져오기에서 두 가지 상태를 저장합니다.

WordPress 상태	EmDash 상태
`publish`	`published`
`draft`	`draft`
`pending`	`draft`
`private`	`draft`
`future`, `trash` 또는 그 밖의 값	`draft`

가져오기 도구는 WordPress의 대기 중, 비공개, 예약, 휴지통 의미를 보존하지 않습니다. EmDash에서 게시하기 전에 해당 항목을 검토하세요.

콘텐츠와 식별자

WXR 소스와 Exporter 소스는 Gutenberg 마크업을 Portable Text로 변환합니다. post는 posts로, page는 pages로, 알려진 사용자 정의 게시물 유형은 컬렉션 슬러그로 매핑합니다. WordPress 내부 게시물 유형은 제외됩니다. 재사용 가능한 블록(wp_block)은 일반 항목이 아니라 EmDash 섹션으로 처리됩니다.

가져온 항목에 대해서는 다음과 같습니다.

WordPress 게시물 슬러그는 사용할 수 있는 경우 EmDash 슬러그가 됩니다.
EmDash는 자체 데이터베이스 ID를 생성합니다.
작성자 매핑은 EmDash 사용자를 연결합니다. 매핑되지 않은 WordPress 작성자는 재사용 가능한 게스트 byline이 될 수 있습니다.
WordPress ID는 메뉴, 댓글, 대표 이미지, 번역 같은 관계를 확인하는 데 일시적으로 사용됩니다. 기존 WXR 항목을 감지하는 데 쓰이는 영구적인 식별자가 아닙니다.

skipExisting을 사용한 WXR 재실행은 컬렉션, 슬러그, 로케일로 기존 항목을 일치시킵니다. 따라서 슬러그가 바뀌면 다른 항목이 생성될 수 있습니다. Exporter 경로도 같은 슬러그와 로케일 검사를 사용하며, 건너뛴 항목으로부터 WordPress ID 관계 맵을 다시 구성합니다.

미디어 복사와 중복 제거

미디어 단계는 각 첨부 파일 URL을 다운로드하고, 다운로드한 바이트 데이터의 SHA-1 해시를 계산한 다음, 해당 콘텐츠 해시를 가진 기존 미디어 행을 찾습니다. 바이트 데이터가 같으면 WordPress URL이 달라도 기존 미디어 레코드를 재사용합니다.

해시는 sha1: 접두사와 함께 저장됩니다. 이는 중복 제거 키이며 보안 서명이 아닙니다. 파일 이름이 같다는 이유만으로 두 URL을 중복으로 간주하지는 않습니다.

미디어를 복사한 후 가져오기 도구는 Portable Text, 텍스트, 문자열, 이미지, 파일 필드에서 일치하는 URL을 다시 작성합니다. 다운로드와 다시 작성된 페이지를 검증할 때까지 WordPress 오리진을 온라인 상태로 유지하세요.

재시도 동작

관리자는 WXR 가져오기에 대한 영구적인 재개 토큰을 저장하지 않습니다. 요청이 실패한 경우:

skip existing을 켠 상태로 분석과 가져오기를 다시 실행합니다.
기존 항목은 컬렉션, 슬러그, 로케일로 건너뜁니다.
이미 저장된 파일에 대해서는 미디어를 다시 실행해도 안전합니다. 바이트 단위로 동일한 다운로드는 콘텐츠 해시를 재사용하기 때문입니다.
다시 시도하기 전에 부분적인 스키마 변경과 슬러그가 바뀐 항목을 확인합니다.

Exporter 흐름은 Worker 제한에 맞도록 청크로 나뉩니다. 브라우저는 요청 사이에 커서와 WordPress-EmDash 관계 맵을 전달합니다. 브라우저가 그 상태를 잃으면 가져오기를 다시 시작하세요. 건너뛴 항목이 콘텐츠 페이지가 처리되면서 관계 맵을 다시 구성합니다.

별도의 emdash import wordpress CLI는 변환된 JSON 파일을 출력 디렉터리에 기록합니다. 이 CLI의 --resume 옵션은 .wp-migration-progress.json을 읽고 거기에 이미 기록된 WordPress 게시물 ID와 첨부 파일 ID를 건너뜁니다. 이 파일 변환 워크플로는 관리자 데이터베이스 가져오기가 아니며, 관리자 요청을 재개 가능하게 만들지도 않습니다.

관리자 API 계약

이 엔드포인트들은 인증이 필요한 관리자 페이지를 구동합니다. import:execute 권한이 있는 관리자 세션과 X-EmDash-Request: 1 헤더가 필요합니다. 성공 응답은 보통 { "success": true, "data": ... } 엔벨로프를 사용하고, 오류는 { "success": false, "error": { "code", "message" } }를 사용합니다.

URL 프로브

POST /_emdash/api/import/probe는 JSON { "url": "https://example.com" }을 받습니다.

data 값은 { success: true, result }입니다. result에는 url, isWordPress, bestMatch, allMatches가 들어 있습니다. 단순한 WordPress REST 일치는 WXR 업로드를 권장하며, REST 직접 가져오기를 활성화하지는 않습니다.

WXR 파일 분석

POST /_emdash/api/import/wordpress/analyze는 file 파트가 있는 multipart/form-data를 받습니다. data 값에는 사이트, 게시물 유형 분석, 첨부 파일 요약, 작성자 요약, 택소노미 개수, 사용자 정의 필드 제안이 들어 있습니다.

스키마 준비

POST /_emdash/api/import/wordpress/prepare는 다음 JSON 형태를 받습니다.

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

data 값에는 success, collectionsCreated, fieldsCreated, 컬렉션별 errors가 들어 있습니다.

WXR 가져오기 실행

POST /_emdash/api/import/wordpress/execute는 다음을 포함한 multipart/form-data를 받습니다.

file: WXR 파일.
config: postTypeMappings, skipExisting, 선택 사항인 authorMappings, 선택 사항인 importSections, 그리고 선택 사항인 가져오기 전체 locale을 담은 JSON 문자열.

data 값에는 success, imported, skipped, errors, byCollection, 그리고 선택 사항인 섹션 및 택소노미 요약이 들어 있습니다.

미디어 복사

POST /_emdash/api/import/wordpress/media는 JSON { "attachments": [...], "stream": true }를 받습니다. 스트리밍이 기본값입니다. 스트리밍 응답은 progress 레코드 뒤에 result 레코드 하나가 이어지는 줄 바꿈 구분 JSON이며, 일반 API 엔벨로프를 사용하지 않습니다. stream을 false로 설정하면 { imported, failed, urlMap }을 감싼 일반 엔벨로프를 받습니다.

미디어 URL 다시 작성

POST /_emdash/api/import/wordpress/rewrite-urls는 JSON { "urlMap": { "old": "new" }, "collections": ["posts"] }를 받습니다. 선택 사항인 컬렉션 목록으로 다시 작성 범위를 제한할 수 있습니다. data 값에는 업데이트된 항목 수와 다시 작성된 URL 수, 그리고 오류가 들어 있습니다.

Exporter API 사용

POST /_emdash/api/import/wordpress-plugin/analyze는 JSON { "url", "token" }을 받으며, token은 WordPress 사용자와 애플리케이션 비밀번호에 대한 Base64 기본 인증 값입니다. data 값은 { success: true, analysis }입니다.

POST /_emdash/api/import/wordpress-plugin/execute는 url, token, config를 포함한 JSON을 받습니다. 관리자는 phase(content, comments, finalize)도 함께 전달합니다. 각 응답에는 done, 선택 사항인 다음 cursor, 부분 result, 그리고 업데이트된 idMap, translationGroups, commentRoots가 담긴 chunk 객체가 들어 있습니다. 관리자는 chunk 값을 병합하고, 누적된 맵을 다음 요청과 함께 보냅니다.

문제 해결

사이트는 감지되지만 직접 가져올 수 없음

wordpress-rest 결과는 프로브일 뿐입니다. WXR 파일을 업로드하거나 EmDash Exporter를 설치한 다음 사이트를 다시 프로브하세요.

게시물 유형이 호환되지 않음

검토 화면에서 게시물 유형을 펼쳐 충돌하는 필드를 찾습니다. 대상 컬렉션을 변경하거나 Content Types에서 해당 필드를 조정하세요. 가져오기 도구는 기존 필드의 유형을 바꾸지 않습니다.

일부 미디어가 실패함

최종 미디어 결과에 실패한 원본 URL이 나열됩니다. 각 URL이 공개되어 있고, 아직 존재하며, 사설 네트워크 주소로 리디렉션되지 않는지 확인하세요. 접근 문제를 해결한 후 미디어 단계를 다시 시도하세요. 이미 완료된 바이트 단위로 동일한 파일은 재사용됩니다.

다음 단계

운영 절차는 WordPress에서 마이그레이션을 참고하세요.
콘텐츠를 가져온 후에는 WordPress 테마 포팅을 참고하세요.
사이트가 사용자 지정 동작에 의존한다면 WordPress 플러그인 포팅을 참고하세요.