클라이언트 재설정
개요
클라이언트 재설정 오류는 클라이언트 영역이 애플리케이션 백엔드와 데이터를 동기화할 수 없는 경우에 발생합니다. 이 상태의 클라이언트는 계속 로컬에서 실행하고 데이터를 저장할 수 있지만 클라이언트 재설정을 수행할 때까지 동기화 변경 집합을 보내거나 받을 수 없습니다. 영역 SDK는 대부분의 시나리오에서 클라이언트 재설정을 자동으로 처리하는 메서드를 제공합니다.
경고
기본값 클라이언트 재설정 프로세스 는 로컬에 성공적으로 저장된 동기화되지 않은 변경 사항을 복구하려고 시도합니다. 클라이언트 애플리케이션 에 손상적인 스키마 변경이 있거나 서버 에서 복구 모드 가 비활성화되어 있는 경우, 클라이언트 재설정 프로세스 는 기기에 로컬로 유지될 수 있는 동기화되지 않은 데이터를 복구할 수 없습니다.
클라이언트 재설정 시나리오는 서버 기록이 클라이언트 기록과 호환되지 않을 때 발생합니다. 클라이언트 재설정의 가장 일반적인 원인은 다음과 같습니다:
Atlas App Services 서버 충돌: 서버가 이전 버전이 있는 백업에서 복원할 수 있습니다. 이 시나리오에서 클라이언트를 재설정하면 클라이언트가 이전 버전으로 재설정되고 클라이언트에 저장되었지만 아직 서버와 동기화되지 않은 모든 변경 사항이 손실됩니다.
동기화 비활성화 및 다시 활성화: App Services UI에서 동기화를 껐다가 다시 켜면 모든 클라이언트에서 클라이언트 재설정을 수행해야 합니다.
클라이언트/백엔드 스키마 불일치: 클라이언트 애플리케이션이 백엔드에 존재하지 않는 Realm 객체 스키마를 사용하면서 백엔드와 동기화를 시도하는 경우, 해당 클라이언트는 클라이언트 재설정을 수행해야 합니다. 이는 한 방향으로만 적용됩니다. 백엔드 스키마에 클라이언트에서 사용되지 않는 Realm 객체 클래스가 포함된 경우 해당 클라이언트는 클라이언트를 재설정할 필요가 없습니다.
클라이언트 최대 오프라인 시간: 클라이언트가 클라이언트 최대 오프라인 시간 일수를 초과해 백엔드와 동기화하지 않은 경우 해당 클라이언트는 동기화되지 않은 로컬 변경 내용을 더 이상 백엔드와 동기화할 수 없습니다. 클라이언트는 마지막 동기화 이후의 모든 로컬 변경 사항을 취소하고 백엔드에서 영역의 현재 상태를 다운로드해야 합니다.
손상적인 스키마 변경: 속성 유형이나 기본 키 변경과 같이 손상적이거나 파괴적인 변경 을 수행하려면 동기화를 종료했다가 다시 허용해야 합니다. 이렇게 하면 클라이언트의 파일 과 관련이 없는 버전으로 동기화된 새 영역 파일 이 생성됩니다. 이 시나리오에서는 클라이언트 재설정 프로세스 가 자동으로 완료될 수 없으며, 앱 에서 수동 클라이언트 재설정 처리기를 제공해야 합니다.
공유 클러스터에서 전용 클러스터로 업그레이드: 공유 클러스터에서 전용 클러스터로 업그레이드하는 경우 이전 클러스터에서 동기화를 종료해야 합니다. 업그레이드한 후 동기화를 다시 활성화할 수 있습니다. 동기화를 껐다가 다시 켜면 모든 클라이언트에 대해 클라이언트 재설정을 수행해야 합니다.
세션 역할 변경: Flexible Sync를 사용하는 동안 사용자의 Flexible Sync 세션 역할을 변경하면 클라이언트 재설정이 수행됩니다. 다음 시나리오는 모두 클라이언트 재설정을 초래합니다:
서버 측의 세션 역할 수정
'적용 시기', 읽기 또는 쓰기 표현식의 확장 값에 대한 변경 사항
사용자에게 다른 세션 역할에 대한 자격을 부여하는 변경 사항
참고
손상적인 스키마 변경에는 앱 스키마 업데이트가 필요합니다.
손상적인 스키마 변경 후 다음을 수행합니다:
모든 클라이언트는 수동으로 클라이언트 재설정을 수행해야 합니다.
손상적인 스키마 변경의 영향을 받는 클라이언트 모델을 업데이트해야 합니다.
클라이언트 재설정 처리
SDK는 클라이언트 재설정의 필요성을 자동으로 감지합니다. SDK는 손상적인 스키마 변경이 발생하는 경우를 제외하고 대부분의 경우 자동으로 클라이언트 재설정을 수행할 수 있습니다.
자동 클라이언트 재설정 중에 클라이언트는 다음을 수행합니다.
백엔드에서 영역의 새 사본을 다운로드합니다.
diff를 수행하여 영역의 원본(로컬) 사본을 백엔드의 새 사본과 동일한 상태로 가져오는 데 필요한 단계를 파악합니다.
해당 단계를 적용하여 로컬 영역을 백엔드와 동기화할 수 있는 상태로 변환합니다.
스키마 변경이 없거나 손상적이지 않은 스키마 변경만 있는 경우 SDK는 아직 백엔드에 동기화되지 않은 모든 로컬 변경 내용을 복구하려고 시도합니다. 또한 아직 클라이언트와 동기화되지 않은 백엔드의 모든 삽입, 업데이트 및 삭제 작업을 적용합니다.
SDK에서 동기화되지 않은 변경 사항을 적용하지 않도록 선택했거나 복구 모드가 동기화되지 않은 변경 사항을 복구할 수 없는 경우, SDK는 백엔드에 아직 동기화되지 않은 로컬 변경 사항을 적용하지 않을 수 있습니다. 이후 아직 클라이언트에 동기화되지 않은 백엔드의 삽입, 업데이트 및 삭제 작업을 적용할 수 있습니다. 로컬 변경 사항을 삭제하려면 선호하는 SDK 버전의
recoverOrDiscard클라이언트 재설정 모드를 선택하세요.새 사본을 폐기합니다. 앱은 diff가 적용된 영역의 원본 사본을 계속 사용합니다.
손상적인 스키마 변경이 발생하거나 자동 클라이언트 재설정이 실패하면 클라이언트 재설정은 앱에서 정의해야 하는 수동 클라이언트 재설정 처리기를 트리거합니다. Realm SDK는 손상적인 스키마 변경이 발생할 경우 클라이언트 재설정을 자동으로 수행할 수 없습니다.
자동 클라이언트 재설정 모드는 수동 복구에 비해 몇 가지 장점이 있습니다:
애플리케이션은 모드를 지정하는 것 외에 사용자 지정 로직을 작성하지 않고도 클라이언트 재설정을 수행할 수 있습니다. 클라이언트 재설정을 수동으로 시작하거나 오류 객체와 상호 작용할 필요가 전혀 없습니다.
애플리케이션은 영역을 닫거나 백엔드 앱과의 연결을 끊거나 수동으로 다시 시작하지 않고도 클라이언트 재설정을 수행할 수 있습니다. 즉, 이러한 상황을 처리하기 위해 로직을 작성할 필요가 없습니다.
백엔드 영역의 상태와 일치하도록 로컬 영역이 업데이트되면 애플리케이션 사용자는 변경 사항에 대한 알림을 받습니다.
동기화되지 않은 변경 내용 복구
Device Sync 구성에서 Client Recovery가 활성화되어 있으면(기본값 그대로) 클라이언트 애플리케이션이 동기화되지 않은 변경 사항을 자동으로 복구할 수 있습니다. 대부분의 시나리오에서 클라이언트 애플리케이션은 클라이언트 재설정 오류가 발생했음을 감지하고 클라이언트 재설정을 처리하는 자동화된 프로세스를 시작할 수 있습니다.
클라이언트가 재설정되면 앱이 정상적으로 열리고 작동할 수 있습니다.
클라이언트 복구는 손상적인 스키마 변경이 있는 경우를 제외하고 클라이언트 재설정에서 동기화되지 않은 데이터를 복구할 수 있습니다. 클라이언트 복구는 기기에서 동기화되지 않은 데이터를 통합하는 방법을 결정할 때 클라이언트 재설정 복구 규칙을 적용합니다.
클라이언트가 동기화되지 않은 데이터를 복구할 수 없는 경우 동기화되지 않은 변경 내용 폐기로 되돌아가도록 선택할 수 있습니다. 이 경우 로컬 데이터는 폐기되지만 클라이언트는 자동으로 클라이언트 재설정을 수행할 수 있습니다. 로컬 변경 사항을 삭제하려면 선호하는 SDK 버전의 recoverOrDiscard 클라이언트 재설정 모드를 선택하세요.
클라이언트 재설정 복구 규칙
손상적인 스키마 변경을 포함하지 않는 클라이언트 재설정에서 Realm SDK는 동기화되지 않은 변경 사항을 복구하려고 시도합니다. SDK는 클라이언트가 재설정되기 전에 로컬에서 생성되었고 동기화되지 않은 객체를 통합합니다. 이러한 규칙은 백엔드와 클라이언트가 모두 동일한 객체를 변경할 때 충돌을 해결하는 방식을 결정합니다.
객체가 서버에서 삭제되었지만 복구 클라이언트에서 수정된 경우 삭제가 우선적으로 적용되고 클라이언트는 업데이트를 삭제합니다.
복구 클라이언트에서는 객체가 삭제되었지만 서버에서는 삭제되지 않은 경우 클라이언트는 삭제 명령을 적용합니다.
동일한 필드에 대한 업데이트가 충돌하는 경우 클라이언트 업데이트가 적용됩니다.
동기화되지 않은 변경 내용 삭제
경고
동기화되지 않은 로컬 변경 사항 영구 삭제
이 클라이언트 재설정 모드는 아직 백엔드에 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제합니다. 애플리케이션에서 동기화되지 않은 변경 사항을 보존해야 하는 경우에는 이 클라이언트 재설정 모드를 사용하지 마세요.
동기화되지 않은 변경 사항 삭제 클라이언트 재설정 모드 는 클라이언트 장치에서 데이터 복구를 시도하지 않고 클라이언트 재설정을 자동으로 처리합니다. 클라이언트 재설정 복구 규칙 이 앱 에서 작동하지 않거나 동기화되지 않은 데이터를 저장할 필요가 없는 경우 이 모드 를 선택할 수 있습니다. 이 모드 가 diff를 사용하여 로컬 영역 을 백엔드 와 동일한 상태 로 가져오면 동기화되지 않은 변경 사항이 영구적으로 삭제됩니다.
동기화되지 않은 변경 사항 삭제 모드는 손상적인 스키마 변경이 발생하는 경우 자동화된 클라이언트 재설정을 수행할 수 없습니다.
수동 클라이언트 재설정
손상적인 스키마 변경이 발생하는 경우, Realm SDK는 클라이언트 재설정을 자동으로 처리할 수 없습니다. 손상적인 스키마 변경이 발생한 경우 수동 클라이언트 재설정 처리기를 정의해야 합니다.
이 경우 수동 클라이언트 재설정 처리기는 사용자에게 앱 업데이트 요청 등의 안내 메시지를 표시합니다. 클라이언트 재설정을 자동으로 처리하는 Realm SDK 버전에서는 의미 있는 복구를 수행할 수 없는 오류 시나리오에서만 수동 클라이언트 재설정이 수행됩니다.
예시
클라이언트 재설정 수행에 대한 자세한 내용은 SDK에 대한 클라이언트 재설정 예시를 확인하세요.
복구 모드 활성화 또는 비활성화
복구 모드는 모든 Device Sync 구성에서 기본적으로 활성화됩니다. 복구 모드를 비활성화하거나 이전에 비활성화한 경우 다시 활성화할 수 있습니다.
사이드바에서 Device Sync 메뉴를 선택합니다.
Advanced Configuration 창을 클릭하여 추가 구성 옵션을 표시합니다.
Enable Client Recovery 토글을 클릭합니다.
Save 버튼을 눌러 변경 사항을 확인합니다.
앱에서 배포 초안을 사용하는 경우 변경 후 애플리케이션을 배포해야 합니다.
다음 pull 명령을 사용하여 앱 의 최신 버전의 로컬 사본을 가져옵니다.
당기기appservices pull --remote="<Your App ID>" 앱의
sync/config.json파일 에 있는is_recovery_mode_disabled속성 을 사용하여 애플리케이션의 클라이언트 최대 오프라인 시간 일수를 구성할 수 있습니다.``sync/config.json``{ ... "is_recovery_mode_disabled": false, ... } 다음 푸시 명령을 사용하여 업데이트된 앱 구성을 배포합니다.
푸시appservices push --remote="<Your App ID>"