여기서 소개하는 기능은 Realm 모바일 플랫폼 프로페셔널 및 엔터프라이즈 에디션에서 제공됩니다. 더 자세한 내용을 알아보고 무료 평가판을 시작해보세요.

Note: 이 문서는 엔터프라이즈 및 프로페셔널 에디션에 제한된 기능만 설명합니다. 설정과 일반적인 사용법 및 문제 해결을 포함한 다른 항목에 대해서는 주 오브젝트 서버 문서를 참고하세요.

설치/업그레이드

Note: 프로페셔널 및 엔터프라이즈 버전은 현재 Linux에서만 사용할 수 있습니다.

빠른 시작 가이드

이 가이드는 같은 시스템에 연속 백업 클라이언트 및 서버와 함께 Realm 오브젝트 서버 엔터프라이즈 에디션을 빠르게 설치하고 기본 설정으로 활성화해서 사용하는 방법을 안내합니다.

# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버와 백업 클라이언트 설치
sudo yum -y install realm-object-server-enterprise
sudo yum -y install realm-object-server-backup-client

# ROS 서비스를 활성화하고 시작하기
sudo chkconfig realm-object-server on
sudo service realm-object-server start

# 백업 서버 서비스를 활성화하고 시작하기
sudo chkconfig realm-object-server-backup-server on
sudo service realm-object-server-backup-server start

# 백업 클라이언트 서비스를 활성화하고 시작하기
sudo chkconfig realm-object-server-backup-client on
sudo service realm-object-server-backup-client start

# 파일이 동기화되는지 확인하기
md5sum /var/lib/realm/object-server/0/user_data/__admin.realm
md5sum /var/lib/realm/object-server-backup-client/0/user_data/__admin.realm
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버와 백업 클라이언트 설치
sudo yum -y install realm-object-server-enterprise
sudo yum -y install realm-object-server-backup-client

# ROS 서비스를 활성화하고 시작하기
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

# 백업 서비스가 실행 중인지 확인하기
sudo systemctl status realm-object-server-backup-server

# 백업 클라이언트 서비스를 활성화하고 시작하기
sudo systemctl enable realm-object-server-backup-client
sudo service realm-object-server-backup-client start

# 파일이 동기화되는지 확인하기
md5sum /var/lib/realm/object-server/0/user_data/__admin.realm
md5sum /var/lib/realm/object-server-backup-client/0/user_data/__admin.realm
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Setup Realm's Enterprise package repository. No need to do it if you already installed the ROS Enterprise.
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# 저장소 업데이트
sudo apt-get update

# Realm 오브젝트 서버 설치하기
sudo apt-get install realm-object-server-enterprise
sudo apt-get install realm-object-server-backup-client

# ROS 서비스를 활성화하고 시작하기
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

# 백업 서비스가 실행 중인지 확인하기
sudo systemctl status realm-object-server-backup-server

# 백업 클라이언트 서비스를 활성화하고 시작하기
sudo systemctl enable realm-object-server-backup-client
sudo service realm-object-server-backup-client start

# 파일이 동기화되는지 확인하기
md5sum /var/lib/realm/object-server/0/user_data/__admin.realm
md5sum /var/lib/realm/object-server-backup-client/0/user_data/__admin.realm

프로페셔널 에디션으로 업그레이드

이 기능은 프로페셔널과 엔터프라이드 에디션에서만 가능합니다. 이 곳에서 더 많은 기능을 알아보고 무료 시험버전을 시작해보세요.

Realm 오브젝트 서버를 프로페셔널 에디션으로 업그레이드하는 경우 먼저 개발자 에디션을 삭제해야 합니다. 그 다음 이메일로 보내드린 접근 토큰을 사용해 배포 환경에 맞게 다음과 같은 단계를 따르세요.

# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 패키지 저장소 설정하기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.rpm.sh | sudo bash

# Realm 오브젝트 서버 설치하기
sudo yum -y install realm-object-server-professional

# 서비스 활성화하고 시작하기
sudo chkconfig realm-object-server on
sudo service realm-object-server start
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 패키지 저장소 설정하기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.rpm.sh | sudo bash

# Realm 오브젝트 서버 설치하기
sudo yum -y install realm-object-server-professional

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 패키지 저장소 설정하기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-professional/script.deb.sh | sudo bash

# 저장소 업데이트
sudo apt-get update

# Realm 오브젝트 서버 설치하기
sudo apt-get install realm-object-server-professional

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

엔터프라이즈 에디션으로 업그레이드

Realm 오브젝트 서버를 엔터프라이즈 에디션으로 업그레이드하는 경우 먼저 개발자/프로페셔널 에디션을 삭제해야 합니다. 그 다음 이메일로 보내드린 접근 토큰을 사용해 배포 환경에 맞게 다음과 같은 단계를 따르세요.

# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 패키지 저장소 설정하기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버 설치하기
sudo yum -y install realm-object-server-enterprise

# 서비스 활성화하고 시작하기
sudo chkconfig realm-object-server on
sudo service realm-object-server start
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 패키지 저장소 설정하기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버 설치하기
sudo yum -y install realm-object-server-enterprise

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 패키지 저장소 설정하기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# 저장소 업데이트
sudo apt-get update

# Realm 오브젝트 서버 설치하기
sudo apt-get install realm-object-server-enterprise

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server

로드 밸런싱

이 기능은 프로페셔널과 엔터프라이드 에디션에서만 가능합니다. 이 곳에서 더 많은 기능을 알아보세요.

Realm 오브젝트 서버는 고성능으로 설계됐으며, 단일 인스턴스로도 수만 개 이상의 동시 연결을 처리할 수 있습니다. 그러나 수백만 이상의 동시 접속이 예상되는 대규모의 애플리케이션의 경우, 여러 서버가 필요할 수 있습니다. Realm 모바일 플랫폼 엔터프라이즈 에디션은 대규모 애플리케이션을 지원하고 있는 Realm 오브젝트 서버라도 얼마든지 그 수에 관계없이 수평적으로 확장할 수 있는 완벽한 솔루션을 제공합니다.

이 시스템은 클라이언트와 서버에 의해 사용되는 양방향 연결을 유지하는 로드 밸런서에 의해 동작합니다.

설치

각 백엔드 노드는 동일한 클러스터의 다른 백엔드 노드와 독립적으로 동작합니다. 각 백엔드 노드는 realm-sync-worker 바이너리의 인스턴스를 실행하는데, realm-sync-worker란 Realm 오브젝트 서버의 일부분으로 주로 실행되는 동기화 작업자의 이름입니다. 설정이 필요하지 않지만 Realm 오브젝트 서버를 실행하는 서버 인스턴스에서 연결할 수 있어야 합니다.

동기화 작업자를 설치하려면 아래 설명처럼 엔터프라이즈 저장소를 설정해야 합니다.

# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 엔터프라이즈 저장소 설정하기. 이미 ROS 엔터프라이즈를 설치했다면 건너 뛰세요.
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버의 독립형 동기화 작업자 설치
sudo yum -y install realm-sync-worker

# /etc/realm/token-signature.pub를 Realm 오브젝트 서버의 것으로 교체합니다

# 서비스 활성화하고 시작하기
sudo chkconfig realm-sync-worker on
sudo service realm-sync-worker start
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 엔터프라이즈 저장소 설정하기. 이미 ROS 엔터프라이즈를 설치했다면 건너 뛰세요.
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버의 독립형 동기화 작업자 설치
sudo yum -y install realm-sync-worker

# /etc/realm/token-signature.pub를 Realm 오브젝트 서버의 것으로 교체합니다

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-sync-worker
sudo systemctl start realm-sync-worker
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 엔터프라이즈 저장소 설정하기. 이미 ROS 엔터프라이즈를 설치했다면 건너 뛰세요.
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# 저장소 업데이트
sudo apt-get update

# Realm 오브젝트 서버 설치하기
sudo apt-get install realm-sync-worker

# /etc/realm/token-signature.pub를 Realm 오브젝트 서버의 것으로 교체합니다

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-sync-worker
sudo systemctl start realm-sync-worker

설정

Realm 오브젝트 서버의 configuration.yml의 “sync.servers” 섹션은 백엔드 노드의 클러스터를 설명합니다. 로드 밸런싱을 위해 각 백엔드 노드는 고유한 ID로 식별될 수 있어야 합니다. ID는 유효한 파일시스템 경로 구성요소라면 어느 문자열이든 가능합니다.

아래 예시를 참고하세요.

sync:
  servers:
  - id: 'alpha'
    address: '::'
    port: 7800
  - id: 'beta'
    address: 'beta.local'
    port: 7800
  - id: 'delta'
    address: 'delta.local'
    port: 7800

예제 설정 파일은 Realm 오브젝트 서버 설치 과정에서 추가 세부 사항으로 제공됩니다.

주소가 IPv6를 사용하는 경우 “0.0.0.0”나 “::”과 같은 모든 인터페이스를 나타내는 IP 주소를 각 클러스터 백엔드 노드의 “address” 필드에 지정하면 특별히 해석됩니다. 이 경우 로컬 동기화 작업자가 “127.0.0.1”나 “::1” 등의 로컬호스트 IP 주소를 수신하기 시작해야 한다고 Realm 오브젝트 서버에 알립니다.

동기화 작업자는 즉시 작업할 수 있으며, 단일 인스턴스에서 여러 작업자를 시작해야 하거나, 127.0.0.1 이외의 인터페이스를 수신해야 하는 경우에만 추가 구성이 필요합니다.

예제 설정은 Realm 오브젝트 서버 설치시 함께 제공되므로 추가 정보를 확인해 볼 수 있습니다.

고가용성

Realm 모바일 플랫폼의 고유한 특성은 오프라인-우선으로 설계됐다는 것입니다. 구조적으로 이는 클라이언트가 데이터의 로컬 복사본을 서버로부터 받고 이를 직접 읽거나 쓴다는 것입니다. 그런 다음 클라이언트 SDK는 네트워크가 연결될 때 비동기적으로 변경 사항을 전송하며, Realm 오브젝트 서버는 이런 변경 사항을 자동으로 통합해서 결정형 방식으로 저장합니다. 이러한 시스템의 결과로 클라이언트 관점에서 본질적으로 높은 가용성을 지니게 됩니다. 네트워크 상태나 서버 작업과 관계없이 항상 로컬에서 읽기 및 쓰기가 가능해집니다.

현재 서비스 손실을 방지할 수 있도록 자동 장애 조치를 지원하는 클러스터링 솔루션을 개발 중으로, 해당 기능은 엔터프라이즈 에디션에서 지원될 예정입니다. 문의하기를 통해 자세한 내용과 미리 사용하는 방법을 알려드립니다.

연속 백업

이 기능은 프로페셔널과 엔터프라이드 에디션에서만 가능합니다. 이 곳에서 더 많은 기능을 알아보세요.

Realm 오브젝트 서버 엔터프라이즈 에디션에는 메인 프로세스와 함께 실행되는 백업 서버 가 포함됩니다. 실행 중인 Realm 오브젝트 서버의 상태를 백업 서버 가 모니터링하다가 관찰하던 오브젝트 서버의 변경 사항을 비동기적으로 하나 이상의 백업 클라이언트 에 전달합니다. 모든 클라이언트는 서버 상태의 복사본을 약간의 지연 후에 받습니다.

엔터프라이즈 에디션과 함께 오브젝트 서버 문서에서 설명된 수동 백업 시스템을 사용할 수 있습니다. (수동 백업은 개발자 에디션과 프로페셔널 에디션에서 제공하는 유일한 백업 시스템입니다.)

연속 백업 시스템은 암호화 및 인증된 엑세스없이 통신합니다! 보안을 유지하려면 백업 시스템을 방화벽 내에서 실행하세요.

백업 서버

백업 서버는 realm-object-server와 realm-sync-worker의 일부로 설치됩니다. 사용하려면 아래 명령어를 실행하세요.

sudo chkconfig realm-object-server-backup-server on
sudo service realm-object-server-backup-server start
# realm-object-server를 시작할 때 자동으로 시작합니다
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server
sudo systemctl status realm-object-server-backup-server
sudo systemctl enable realm-object-server
sudo systemctl start realm-object-server
sudo systemctl status realm-object-server-backup-server

백업 섹션 아래의 Realm 오브젝트 서버의 YAML 파일(/etc/realm/configuration.yml)에서 설정을 구성합니다. 백업 서버를 위한 키는 다음과 같습니다.

Configuration key Default Description
backup.enable true 백업 중단은 false 설정
backup.network.listen_address 127.0.0.1 IP 주소/인터페이스
backup.network.listen_port 27810 백업의 수신 포트
backup.logging.level info Logging 레벨
backup.logging.path /var/log/realm-object-server-backup-server.log (Linux) Log 파일 경로, stderr로 보내려면 빈 값

동기화 작업자 클러스트의 노드를 백업하는 경우, 백업 서버는 /etc/realm/sync-worker-configuration.yml에 위치한 동기화 작업자의 설정 파일을 대신 읽습니다.

백업 클라이언트

Realm 오브젝트 서버 백업 클라이언트는 백업이 필요한 모든 시스템에서 시작되며, 별도의 YAML 파일에서 설정됩니다.

백업 클라이언트를 설정하려면, 아래 설명대로 엔터프라이즈 저장소를 설정해야 합니다.

# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 엔터프라이즈 패키지 저장소 설정. ROS 엔터프라이즈를 설치한 경우 건너뛰기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버 설치하기 Backup Client
sudo yum -y install realm-object-server-backup-client

# 백업이 설정된 ROS를 가리키도록 설정 편집. 기본 설정은 ROS와 백업 서버가 동일한 시스템에 있다고 가정
vim /etc/realm/object-server-backup-client.yml

# 서비스 활성화하고 시작하기
sudo chkconfig realm-object-server-backup-client on
sudo service realm-object-server-backup-client start
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 엔터프라이즈 패키지 저장소 설정. ROS 엔터프라이즈를 설치한 경우 건너뛰기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.rpm.sh | sudo bash

# Realm 오브젝트 서버 설치하기
sudo yum -y install realm-object-server-backup-client

# 백업이 설정된 ROS를 가리키도록 설정 편집. 기본 설정은 ROS와 백업 서버가 동일한 시스템에 있다고 가정.
vim /etc/realm/object-server-backup-client.yml

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-object-server-backup-client
sudo systemctl start realm-object-server-backup-client
# 토큰 변수 설정하기
export PACKAGECLOUD_TOKEN=<the token you received via email>

# Realm 엔터프라이즈 패키지 저장소 설정. ROS 엔터프라이즈를 설치한 경우 건너뛰기
curl -s https://$PACKAGECLOUD_TOKEN:@packagecloud.io/install/repositories/realm/ros-enterprise/script.deb.sh | sudo bash

# 저장소 업데이트
sudo apt-get update

# Realm 오브젝트 서버 설치하기
sudo apt-get install realm-object-server-backup-client

# 백업이 설정된 ROS를 가리키도록 설정 편집. 기본 설정은 ROS와 백업 서버가 동일한 시스템에 있다고 가정.
vim /etc/realm/object-server-backup-client.yml

# 서비스 활성화하고 시작하기
sudo systemctl enable realm-object-server-backup-client
sudo systemctl start realm-object-server-backup-client

설정 파일은 /etc/realm/object-server-backup-client.yml에 있습니다.

백업 클라이언트 설정 키는 다음과 같습니다.

Configuration key Default Description
storage.root_path   The directory where the backup should be stored. A recovered Realm Object Server can be started with this directory as root path.
network.server_address   The IP address/interface of the backup server.
network.server_port 27810 The IP address/interface of the backup server.
network.reconnect_delay 2000 The delay (in milliseconds) between attempts to reach the backup server. The client automatically reconnects after connection loss.
logging.level info Logging levels described in Logging
logging.path /var/log/realm-object-server-backup-client.log (Linux) Log file path. Empty value outputs to stderr.

모니터링

Realm 오브젝트 서버는 localhost:8125를 수신하는 statsd 에 대한 메트릭 전송을 지원합니다. 이런 메트릭 모니터링을 위해 graphite 등의 시스템에 전달할 수 있습니다.

모든 메트릭 키는 realm.<hostname> 접두어로 시작합니다.

realm.example.com.server.connection.accept.succeeded
realm.example.com.server.connection.accept.failed
realm.example.com.server.protocol.bind.received
realm.example.com.auth.password.attempted
realm.example.com.auth.password.failed
realm.example.com.auth.password.failure.username_invalid
realm.example.com.auth.password.failure.password_check_failed

카운터

Realm 오브젝트 서버가 시작될 때마다 아래 카운터가 증가합니다.

  • <prefix>.server.started

아래 카운터는 동기화 시작이 실패할 때 증가합니다. 이는 클라이언트에서 Realm 파일을 삭제하고 서버로부터 다시 로드해야 함을 나타냅니다.

  • <prefix>.protocol.ident.failure.bad_server_version
  • <prefix>.protocol.ident.failure.diverging_histories
  • <prefix>.protocol.ident.failure.bad_client_file_ident

아래 카운터는 세션 시작과 종료 시점에 증가합니다. 세션은 인증 전, 연결 시점에서 시작되는 것으로 간주합니다.

  • <prefix>.session.started
  • <prefix>.session.terminated

토큰과 관련된 실패를 나타내는 카운터입니다.

  • <prefix>.protocol.client.token.failure.invalid_base64
  • <prefix>.protocol.client.token.failure.invalid_json
  • <prefix>.protocol.client.token.failure.missing_key: 키가 없으므로 토큰이 인증 없이 수락 됩니다.
  • <prefix>.protocol.client.token.failure.signature_mismatch
  • <prefix>.protocol.client.token.failure.expired

아래 카운터는 송수신되는 여러 유형의 동기화 프로토콜 메시지를 나타냅니다.

  • <prefix>.protocol.download.sent
  • <prefix>.protocol.bind.received
  • <prefix>.protocol.client.received
  • <prefix>.protocol.ident.received
  • <prefix>.protocol.mark.received
  • <prefix>.protocol.refresh.received
  • <prefix>.protocol.unbind.received
  • <prefix>.protocol.upload.received

아래 카운터는 프로토콜 메시지 처리 중의 오류를 추적합니다.

  • Bind
    • <prefix>.protocol.bind.failure.bad_authentication
    • <prefix>.protocol.bind.failure.illegal_realm_path
    • <prefix>.protocol.bind.failure.permission_denied
    • <prefix>.protocol.bind.failure.reuse_of_session_ident
    • 토큰이 아직 제공되지 않았으므로 token_expired 카운터가 없습니다. 그러나 바인드 메시지에서 제공된 토큰을 검사했는데 만료됐거나 유효하지 않은 경우 bad_authentication이 발생합니다.
  • Ident
    • <prefix>.protocol.ident.failure.bad_server_file_ident
    • <prefix>.protocol.ident.failure.bound_in_other_session
    • <prefix>.protocol.ident.failure.permission_denied
    • <prefix>.protocol.ident.failure.token_expired
  • Refresh
    • <prefix>.protocol.refresh.failure.bad_authentication
    • <prefix>.protocol.refresh.failure.permission_denied
    • 현재 토큰이 만료된 상태에서 새 토큰을 제공하는 것을 오류로 간주하지 않으므로 token_expired 카운터가 없습니다. 그러나 리프레시 메시지에서 제공된 토큰을 검사했는데 만료됐거나 유효하지 않은 경우 bad_authentication이 발생합니다.
  • Upload
    • <prefix>.protocol.upload.failure.bad_changeset
    • <prefix>.protocol.upload.failure.bad_client_version
    • <prefix>.protocol.upload.failure.bad_server_version
    • <prefix>.protocol.upload.failure.permission_denied
    • <prefix>.protocol.upload.failure.token_expired
  • Mark
    • <prefix>.protocol.mark.failure.token_expired

하위 레벨 프로토콜 에러를 추적하는 카운터입니다.

  • <prefix>.protocol.read.head.error.bad_message_before_activation
  • <prefix>.protocol.read.head.error.bad_session_ident
  • <prefix>.protocol.read.head.error.bad_syntax
  • <prefix>.protocol.read.head.error.ident_message_after_activation
  • <prefix>.protocol.read.head.error.limits_exceeded
  • <prefix>.protocol.read.head.error.message_after_unbind
  • <prefix>.protocol.read.head.error.premature_ident_message
  • <prefix>.protocol.read.head.error.unknown_message
  • <prefix>.protocol.read.head.error.wrong_protocol_version

모든 프로토콜 에러는 connection.erroredsession.errored에 대해 카운트됩니다.

  • <prefix>.protocol.connection.errored
  • <prefix>.protocol.session.errored

마지막으로 아래 카운터는 연결 이벤트를 추적합니다.

  • <prefix>.connection.accept.failed
  • <prefix>.connection.accept.succeeded
  • <prefix>.connection.read.failure.limits_exceeded
  • <prefix>.connection.read.failed
  • <prefix>.connection.write.failed
  • <prefix>.connection.started
  • <prefix>.connection.terminated
  • <prefix>.connection.removed

게이지

현재 열려있는 연결/세션 수를 나타냅니다. 하나의 연결을 통해 여러 세션을 제공할 수 있습니다.

  • <prefix>.connection.opened
  • <prefix>.session.opened

프로페셔널 및 엔터프라이즈 API 활성화

Node.js 애플리케이션에서 이벤트 핸들링, 데이터 접근, 데이터 커넥터 기능을 사용하려면 접근 토큰 을 애플리케이션에 포함해서 API를 활성화해야 합니다. (이 토큰은 평가 버전에 가입하거나 프로페셔널 또는 엔터프라이즈 에디션을 구매하는 시점에 이메일을 통해 전송됩니다.) Node.js 애플리케이션의 시작 부분에서 토큰을 포함하고 오브젝트 서버에 대한 setAccessToken 호출을 만듭니다.

var token = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";

// 프로페셔널 에디션 API 잠금 해제
Realm.Sync.setAccessToken(token);

접근 토큰을 코드에 저장하는 대신 파일에서 불러올 수도 있습니다.

RealmSync.setAccessToken(fs.readFileSync('./access-token', 'utf-8'));

이벤트 핸들링

Realm 오브젝트 서버의 독점적인 기능은 이벤트 핸들링입니다. 이 기능은 Realm 객체 서버에 걸리는 전역 이벤트 리스너 API를 통해 서버측 Node.js SDK가 제공되므로 Realm 전체의 변경 사항을 관찰할 수 있습니다. 즉, 모든 Realm, 혹은 특정 패턴과 일치하는 Realm의 변화를 수신할 수 있습니다. 예를 들어 사용자 설정 데이터를 가상 경로가 /~/settings인 각 사용자마다 고유한 Realm으로 분리하는 앱 구조라면 모든 사용자의 settings Realm의 변경 사항에 반응하는 리스너를 설정할 수 있습니다.

변경 사항이 서버로 동기화될 때마다 변경 사항에 대한 응답으로 사용자가 정의한 서버측 로직을 실행할 수 있는 알림이 발동됩니다. 이 알림에서 업데이트된 Realm의 가상 경로와 Realm 객체, 변경된 객체에 대한 정밀한 알림이 제공됩니다. 최종으로 동기화된 트랜잭션에서 삽입, 삭제, 수정된 객체의 클래스 이름별로 분류된 객체 색인은 변경 세트에서 볼 수 있습니다.

이벤트 핸들러 생성

Realm의 이벤트 핸들링을 사용하려면 간단한 Node.js 애플리케이션을 만들어야 합니다.

서버 파일을 저장할 디렉터리를 만들고 package.json 파일을 생성합니다. Node.js와 npm, npm 패키지 매니저는 이 JSON 파일로 애플리케이션을 정의하고 외부 디펜던시를 지정합니다.

npm init를 사용해서 대화 형식으로 이 파일을 만들 수도 있습니다. 텍스트 편집기를 사용해서 아래와 같은 간단한 구조 파일을 직접 만들어도 됩니다.

{
    "name": "MyApp",
    "version": "0.0.1",
    "main": "index.js",
    "author": "Your Name",
    "description": "My Cool Realm App",
    "dependencies": {
        "realm": "file:realm-1.0.0-professional.tgz"
    }
}

다운로드한 Realm 모바일 플랫폼 아카이브를 file: 디펜던시로 지정합니다. 이 아카이브는 package.json 파일이 있는 디렉터리에 있어야 합니다. (실제 디스크에 있는 파일 이름이 package.json의 파일 이름과 동일한지 확인하세요.)

애플리케이션에 다른 의존성이 있다면 dependencies 섹션에 추가합니다.

package.json를 올바르게 설정했다면 아래 명령어를 입력하세요.

npm install

이 명령어는 디펜던시에 있는 모든 모듈을 다운로드하고 압축을 풀어서 설정합니다.

이벤트 핸들러는 어드민 권한으로 오브젝트 서버에 접근해야 하므로 오브젝트 서버의 어드민 토큰이 필요합니다. Linux에서는 다음 명령어로 토큰을 볼 수 있습니다.

cat /etc/realm/admin_token.base64

macOS에서는 Realm 모바일 플랫폼 폴더 내의 realm-object-server 폴더에 토큰이 저장돼 있습니다. 해당 폴더로 이동해서 아래 명령어로 토큰을 확인하세요.

cd path-to/realm-mobile-platform
cat realm-object-server/admin_token.base64

샘플 index.js 파일은 아래와 같습니다. 이 예제는 /~/private라는 가상 경로에 위치한 사용자별 개인 Realm에 대한 변경 사항을 수신합니다. 해당 Realm에서 업데이트된 Coupon 객체를 찾아서 코드를 검증합니다. 아직 검증되지 않았다면 검증 결과를 Coupon 객체의 isValid 속성에 넣습니다.

var Realm = require('realm');

var ACCESS_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";

// 프로페셔널 에디션 API 잠금 해제
Realm.Sync.setAccessToken(ACCESS_TOKEN); 

// 여기에 Realm 어드민 토큰을 입력
//   Linux:  cat /etc/realm/admin_token.base64
//   macOS:  cat realm-object-server/admin_token.base64
var ADMIN_TOKEN = 'ADMIN_TOKEN';

// Realm 오브젝트 서버의 URL
var SERVER_URL = 'realm://127.0.0.1:9080';

// 정규 표현식을 넣으면 관찰할 Realm 파일을 제한합니다.
// 이 작업은 별도의 단계로 수행되므로
// 필요하지 않은 경우 정밀한 변경 세트를 계산하는데 비용이 소비되지 않습니다.
var NOTIFIER_PATH = '/^\/([0-9a-f]+)\/private$/';

// 변경 사항이 있을 때마다 관찰된 모든 Realm 파일에 대해 handleChange 콜백이 호출됩니다.
// 이 필드에는 경로, Realm, 변경 전의 Realm 버전,
// 이 변경에서 추가, 삭제, 수정된 모든 객체를 나타내는 인덱스가 포함됩니다.
function handleChange(changeEvent) {
  // 사용자 개인 Realm에 대한 업데이트만 구독하는 필터를 사용한다고 가정하고
  // 가상 경로에서 사용자 ID를 추출합니다.
  var matches = changeEvent.path.match(/^\/([0-9a-f]+)\/private$/);
  var userId = matches[1];

  var realm = changeEvent.realm;
  var coupons = realm.objects('Coupon');
  var couponIndexes = changeEvent.changes.Coupon.insertions;

  for (var couponIndex in couponIndexes) {
    var coupon = coupons[couponIndex];
    if (coupon.isValid !== undefined) {
      var isValid = verifyCouponForUser(coupon, userId);
      // 주의: 여기에 작성하면 후속 알림이 발동하므로
      // 이로 인해 무한한 변경이 발생하지 않도록 주의하세요!
      realm.write(function() {
        coupon.isValid = isValid;
      });
    }
  }
}

// 어드민 사용자 생성
var adminUser = Realm.Sync.User.adminUser(adminToken);

// 이벤트 핸들러 콜백 등록
Realm.Sync.addListener(SERVER_URL, adminUser, NOTIFIER_PATH, 'change', handleChange);

console.log('Listening for Realm changes');

다른 서비스와 통합

다른 서비스와 이벤트 핸들링 프레임워크를 통합하는 전체 예제는 스캐너 앱 튜토리얼을 참고하세요. 예제의 경우 IBM Watson의 Bluemix와 통합했습니다.

데이터 접근

Realm 오브젝트 서버 프로페셔널 및 엔터프라이즈 에디션을 사용하면 서버를 시작할 때 생성된 관리 토큰을 사용해서 모든 공유 Realm 서버에 접근하고 이를 변경할 수 있습니다. 즉, 해당 Realm의 모든 데이터에 접근할 수 있습니다.

Linux에서 어드민 토큰을 검색하려면 아래 명령어를 사용하세요.

cat /etc/realm/admin_token.base64

macOS에서는 토큰이 zip 파일 내부의 realm-object-server 폴더에 저장돼 있습니다.

cat realm-object-server/admin_token.base64

이 토큰을 Realm.Sync.User 객체를 동기적으로 생성할 수 있습니다. 이렇게 만든 사용자 객체를 Realm 생성자에 넘겨서 서버 측의 모든 Realm과 연결할 수 있습니다.

// 어드민 사용자를 이용해서 Realm 열기
var adminToken = '3x4mpl3T0k3n…';
var adminUser = Realm.Sync.User.adminUser(adminToken);
var realm = new Realm({
  sync: {
    user: admin_user,
    url: 'realm://object-server-url:9080/my-realm',
  },
  schema: [{...}
  }]
});

어드민 사용자를 사용하면 Realm URL은 관리자가 아닌 인증에서 사용자 ID로 해석되는 ~ 문자를 포함하지 않습니다. 어드민 사용자에게는 사용자 ID가 없습니다. 비관리자 인증에 대해서는 오브젝트 서버 접근 제어 문서의 인증 섹션을 확인하세요.

데이터 커넥터

이 기능은 프로페셔널과 엔터프라이드 에디션에서만 가능합니다. 이 곳에서 더 많은 기능을 알아보세요.

Realm 오브젝트 서버 엔터프라이즈 에디션은 모든 하위 오브젝트 서버 작업 및 데이터에 접근할 수 있는 Node.js 기반의 어댑터 API를 제공합니다. 이 API으로 동기화된 Realm을 PostgreSQL와 같은 레거시 데이터베이스와 상호 작용하도록 할 수 있습니다. Realm은 외부 데이터베이스와 실시간으로 동기화됩니다. 클라이언트 애플리케이션에서는 Realm 모바일 데이터베이스 API를 사용해서 실시간 네이티브 객체 작업의 이점을 누릴 수 있습니다.

어댑터 API는 앞서 설명한 이벤트 핸들러 API와 매우 유사한 방식으로 설정합니다. 서버 파일이 있는 디렉터리에 간단한 Node.js 애플리케이션을 만들고, npm 디펜던시를 위한 package.json 파일을 만들거나, npm init으로 해당 파일을 대화 형식으로 생성합니다. Realm 모바일 플랫폼 EE 에디션 아카이브를 file: 디펜던시에 설정해줘야 하며, 해당 아카이브는 package.json 파일과 동일한 디렉터리에 있어야 합니다. (package.json의 파일 이름이 실제 디스크의 파일 이름과 같은지 확인하세요!)

{
    "name": "MyApp",
    "version": "0.0.1",
    "main": "index.js",
    "author": "Your Name",
    "description": "My Cool Realm App",
    "dependencies": {
        "realm": "file:realm-1.0.0-enterprise.tgz"
    }
}

다른 의존성을 모두 지정했으면, 모듈을 다운로드하고 압축 해제한 후 설정하는 npm install 명령어를 사용하세요.

이벤트 핸들러 API와 마찬가지로 어드민 권한으로 오브젝트 서버에 접근해야 하므로 오브젝트 서버의 어드민 토큰이 필요합니다. Lunux에서는 다음 명령어로 토큰을 볼 수 있습니다.

cat /etc/realm/admin_token.base64

OmacOS에서는 Realm 모바일 플랫폼 폴더 내의 realm-object-server 폴더에 토큰이 저장돼 있습니다. 해당 폴더로 이동해서 아래 명령어로 토큰을 확인하세요.

cd path-to/realm-mobile-platform
cat realm-object-server/admin_token.base64

어댑터 API를 사용하려면 오브젝트 서버에서 명령을 수신하고 외부 데이터베이스의 API를 호출해서 읽고 쓰는 번역기 역할을 해당 Node.js 애플리케이션이 수행해야 합니다. 다음 코드에 샘플 애플리케이션을 소개합니다.

var Realm = require('realm');

var ACCESS_TOKEN = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...";

// Professional 에디션 API 잠금 해제
Realm.Sync.setAccessToken(ACCESS_TOKEN); 

var adapterConfig = {
  // 여기에 Realm 어드민 토큰을 입력
  //   Linux:  cat /etc/realm/admin_token.base64
  //   macOS:  cat realm-object-server/admin_token.base64
  admin_token: 'ADMIN_TOKEN',

  // Realm 오브젝트 서버의 URL
  server_url: 'realms://127.0.0.1:9080',

  // 어댑터 API 파일의 로컬 경로
  local_path: './adapter',

  // 관찰할 Realm을 한정할 정규 표현식
  realm_path_regex: '/^\/([0-9a-f]+)\/private$/'
};

class CustomAdapter {
  constructor(config) {
    this.adapter = new Realm.Sync.Adapter(
      config.local_path,
      config.server_url,
      Realm.Sync.User.adminUser(config.admin_token),
      config.realm_path_regex,

      // 이 콜백은 새 트랜잭션을 사용할 수 있을 때마다 지정된 경로를 처리하기 위해 호출됩니다.
      // 인자는 변경 사항을 사용할 수 있는 Realm 경로입니다.
      // realm_path_regex와 일치하는 모든 Realm에 대해 호출됩니다.
      (realm_path) => {
        var current_instructions = this.adapter.current(realm_path);
        while (current_instructions) {
          // 정의된 경우 현재 명령어 배열을 처리합니다
          this.process_instructions(current_instructions);

          // 다음 트랜잭션 진행을 위해 호출됩니다.
          this.adapter.advance(realm_path);
          current_instructions = this.adapter.current(realm_path);
        }
      }
    )
  }

  // Adapter.current(path)에서 반환된 명령어 리스트를 넘깁니다
  process_instructions(instructions) {
    instructions.forEach((instruction) => {
        // 각 유형의 명령어에 대한 연산을 수행합니다
        switch (instruction.type) {
          case 'INSERT':
            insert_object(instruction.object_type, instruction.identity, instruction.values);
            break;
          case 'DELETE':
            delete_object(instruction.object_type, instruction.identity);
            break;
          // ... 다른 모든 관련 명령어 유형에 대한 핸들러를 추가하세요
          default:
            break;
        }
      })
  }
}

Adapter.current에서 반환된 각 명령어 객체는 다음 문자열 중 하나의 type을 가집니다. 명령 처리를 위한 데이터를 포함하는 둘 이상의 다른 속성도 설정됩니다.

  • INSERT: 새 객체 삽입
    • object_type: 삽입되는 객체 타입
    • identity: 객체의 기본 키 값이나 객체의 행 인덱스
    • values: 삽입할 객체의 속성 이름과 속성 값의 맵
  • SET: 기존 객체의 속성 값 설정
    • object_type: 객체 타입
    • identity: 객체의 기본 키 값이나 객체의 행 인덱스
    • values: 객체를 업데이트할 속성 이름과 속성 값의 맵
  • DELETE: 기존 객체 삭제
    • object_type: 객체 타입
    • identity: 객체의 기본 키 값이나 객체의 행 인덱스
  • CLEAR: 주어진 타입의 객체를 모두 삭제
    • object_type: 객체 타입
  • LIST_SET: 주어진 리스트 인덱스의 모든 객체를 다른 객체로 설정
    • object_type: 객체 타입
    • identity: 객체의 기본 키
    • property: 변형할 리스트 속성의 속성 이름
    • list_index: 설정할 리스트 인덱스
    • object_identity: 설정되는 객체의 기본 키나 객체의 행 인덱스
  • LIST_INSERT: 리스트의 주어진 인덱스에 객체 삽입
    • object_type: 객체 타입
    • identity: 객체의 기본 키
    • property: 변형할 리스트 속성의 속성 이름
    • list_index: 삽입할 리스트 인덱스
    • object_identity: 삽입할 객체의 기본 키나 객체의 행 인덱스
  • LIST_ERASE: 주어진 인덱스에서 리스트의 객체 삭제: 리스트에서 객체를 지우지만 Realm에는 존속
    • object_type: 객체 타입
    • identity: 객체의 기본 키
    • property: 변형할 리스트 속성의 속성 이름
    • list_index: 삭제할 리스트 인덱스
  • LIST_CLEAR: 모든 객체를 삭제하고 리스트 제거: 객체는 Realm에 존속
    • object_type: 객체 타입
    • identity: 객체의 기본 키
    • property: 삭제할 리스트 속성의 속성 이름
  • ADD_TYPE: 새 타입 추가
    • object_type: 타입 이름
    • primary_key: 타입의 키 속성 이름
    • properties: Realm.ObjectSchema에 설명된 속성 맵
  • ADD_PROPERTIES: 기존 타입에 속성 추가
  • CHANGE_IDENTITY: 기존 객체의 행 인덕스 변경: 기본 키가 있는 객체에는 호출되지 않음
    • object_type: 객체 타입
    • identity: 객체의 이전 행 값
    • new_identity: 객체의 새로운 행 값

모든 명령어 유형과 전달되는 데이터를 포함한 상세 정보는 Realm.Sync.Adapter 클래스의 API 참조 문서를 확인하세요.

PostgreSQL 데이터 커넥터는 이미 구현됐으며, MongoDB, Microsoft SQL 서버 등 더 많은 작업을 진행하고 있습니다. 모든 데이터 커넥터는 애플리케이션의 특정 요구에 맞게 커스터마이징할 수 있습니다. Realm 엔터프라이즈 고객이시라면 담당자에게 자세한 내용을 문의하세요.