Infrascale Online Backup Recovery Manager (OBRM) includes SDK to provide reliable integration with external systems in scope of client PC.
It supports direct calls like start jobs, getting statistics etc.
Also client can subscribe callbacks to receive notifications
Service contract that supports direct calls. Supported operations:
Creates session for specific backup account.
Returns Identity that must be used for all further operations
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Login | Backup account user name | string |
Password | Backup account password | string |
Output fields:
Output Value | Description | |
---|---|---|
Token | Defines backup account session. Used as input for all operations in backup account scope | string |
Faults:
Returns information about signed in account.
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | object |
Refresh | Ask Cloud for updated account information and update AccountInfo state in the service cache | bool |
Output fields:
Output Value | Description | Type / Validation Rules |
---|---|---|
AccountSize | Storage quota for account, bytes | long |
CurrentBackupServerName | Address of the Backup Server | string |
CurrentUploadServerName | Address of the Upload Server | string |
Email addresses string, on which email report will be sent. | string Splitted by ';' or ' ' or ','. | |
EntityId | ID of the Partner/Distributor, i.e. the root of the hierarchy thee. | int, >=0 |
HasConfiguredExchangeBackupset | User has configured Exchange backupset | bool |
HasConfiguredMsSqlBackupset | User has configured MsSql backupset | bool |
IsBackupBlockedDueToAccountOverQuota | Backup is not available for current account due to exceeding the limit of the stored data | bool |
Login | Account Login | string |
SendEmailReport | Sending of the reports is enabled for account | bool |
SecurityType | The type of the security for current account:
| enum SecurityTypeContract |
UsedSpace | Used space utilization by contained accounts, bytes | long |
Faults:
[Test] public void GetAccountInfo_Ok() { _client = new InfrascaleClient(); _client.Connect(); var signInResponse = _client.SignIn(new SignInRequest { Credentials = new CredentialsContract { Login = _testAccount, Password = _testAccountPassword } }); var accountInfo = _client.GetAccountInfo(new GetAccountInfoRequest { Identity = signInResponse.Identity}); Tools.PrintAccountInfo(accountInfo.AccountInfo); _client.SignOut(new SignOutRequest { Identity = signInResponse.Identity }); _client.Disconnect(); } |
Login: sdk.test@sosonlinebackup.com Account Size: 10737418240 UsedSpace: 0 Email: sdk.test@sosonlinebackup.com Is blocked by overquota: False SecurityType: Regular Send backup report by email: False |
Allows to receive notification about events are occurred in scope of specific backup account
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | object |
Output fields: N/A
Faults:
Stops receiving notification about events are occurred in scope of specific backup account
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | object |
Output fields: N/A
Faults:
Retrieves job's state by JobId
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | object |
JobId | Identifies running job. | string |
Output fields:
Output Value | Description | |
---|---|---|
SessionState | identifies current state | enum: Undefined, |
StartedUtc | When job started in UTC | DatreTime |
CompletedUtc | When job completed | DateTime, optional |
ProgressPercentage | Execution progress | float |
ProcessedFiles | size and count of processed files | object |
RemainingFiles | size and count of remaining files | object |
FailedFiles | size and count of remaining files | object |
ErrorMessage | error details | string |
Faults:
Starts RefreshRecoveryInfo job that refreshes local db of metadata by syncing it with backup server. For huge backup sets - potentially long running task
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Output fields:
Output Value | Description | |
---|---|---|
JobSession | created job session with:
| RefreshRecoveryInfoJobSessionContract |
Retrieves the list of folders and files available for recovery at specified Path. If Path is not specified returns a list of systems
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Filter | filter object with includes:
| RecoveryFilterContract |
Path | Path of directory to load children from | string |
Output fields:
Output Value | Description | |
---|---|---|
Items | array of recovery items which include Path and can be one of two types:
| array of RecoveryItemContract |
[Test] public void ExtarctAllRecoveryTree_Ok() { //Init SDK _client = new InfrascaleClient(); _client.Connect(); var signInResponse = _client.SignIn(new SignInRequest { Credentials = new CredentialsContract { Login = _testAccount, Password = _testAccountPassword } }); RefreshRecoveryInfo(signInResponse.Identity); //Extract metadata items var request = new GetRecoveryItemsRequest { Identity = signInResponse.Identity, Path = Environment.MachineName }; var output = _client.GetRecoveryItems(request); //Handle files tree PrintTree(output); //Detach client _client.SignOut(new SignOutRequest { Identity = signInResponse.Identity }); _client.Disconnect(); } public static void PrintTree(GetRecoveryItemsResponse response) { Action<RecoveryItemContract, int> handleLevel = null; handleLevel = (treeItem, level) => { var padding = Enumerable.Range(0, level).Aggregate(new StringBuilder(), (sb, i) => sb.Append(" ")); var dir = treeItem as RecoveryDirectoryContract; if (dir != null) { foreach (var dirItem in dir.Children) { if (dirItem is RecoveryDirectoryContract) Console.WriteLine(padding + dirItem.Path); else Console.WriteLine(padding + Path.GetFileName(dirItem.Path)); handleLevel(dirItem, level + 1); } } }; foreach (var item in response.Items) { Console.WriteLine(item.Path); handleLevel(item, 0); } } public static void RefreshRecoveryInfo(IdentityContract identity) { _client.SubscribeCallback(new SubscribeCallbackRequest { Identity = identity }); bool isCompleted = false; Action<JobSessionContract> isCompletedFunc = contract => isCompleted = contract.JobType == JobTypeContract.RefreshRecoveryInfo; _client.JobCompleted += isCompletedFunc; _client.RunRefreshRecoveryInfoJob(new RunRefreshRecoveryInfoJobRequest { Identity = identity }); while (!isCompleted) { Thread.Sleep(100); } _client.JobCompleted -= isCompletedFunc; } |
ALEXK\C: ALEXK\D: |
Sample filter to get items for the last 7 days where filename contains "123", size between 1 byte and 1 megabyte and located on disc C: var filter = new RecoveryFilterContract { DateFrom = DateTime.Today.AddDays(-7), DateTo = DateTime.Today, FileName = "123", FileSizeInKbFrom = 1, FileSizeInKbTo = 1024, PathFilter = "C:\\" } |
Starts recovery job
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Job | job object with includes:
| RecoveryJobContract |
Output fields:
Output Value | Description | |
---|---|---|
JobSession | job details including RecoveryProgress | RecoveryJobSessionContract |
Occurs when new job starts executing
Fields:
Value | Description | Type |
---|---|---|
JobSessionContract | job details | JobSessionContract |
Occurs when job progress is updated
Fields:
Value | Description | Type |
---|---|---|
JobSessionContract | job details | JobSessionContract |
Occurs when job is completed
Fields:
Value | Description | Type |
---|---|---|
JobSessionContract | job details | JobSessionContract |
Occurs when something is happened during backup
Fields:
Value | Description | Type |
---|---|---|
JobSessionContract | Array of JobEvent | BackupJobEventContract |
[Test] public void ListenBackupEvents_Ok() { _client = new InfrascaleClient(); _client.Connect(); var signInResponse = _client.SignIn(new SignInRequest { Credentials = new CredentialsContract { Login = _testAccount, Password = _testAccountPassword } }); _client.JobStarted += s => Tools.PrintBackupSession("Backup Started", s as BackupJobSessionContract); _client.JobProgress += s => Tools.PrintBackupSession("Backup Progress", s as BackupJobSessionContract); _client.JobCompleted += s => Tools.PrintBackupSession("Backup Completed", s as BackupJobSessionContract); _client.SubscribeCallback(new SubscribeCallbackRequest { Identity = signInResponse.Identity}); _backupProcess = Tools.EmulateBackup(_testStorageDb, _storageDbBackupPath, _storageDbPath, _testAccount, _testAccountPassword, _obrmFolder); _backupProcess.WaitForExit(300000); _client.SignOut(new SignOutRequest { Identity = signInResponse.Identity }); _client.Disconnect(); } |
Event: Backup Started JobType: Backup ProgressPercentage: 0 CreatedUtc: 01.01.0001 0:00:00 StartedUtc: CompletedUtc: AccountLogin: State: Undefined ErrorMessage: Event: Backup Completed JobType: Backup ProgressPercentage: 0 CreatedUtc: 01.01.0001 0:00:00 StartedUtc: CompletedUtc: AccountLogin: State: Undefined ErrorMessage: Processed Files Count: 0 Processed Files Size: 0 Remaining Files Count: 0 Remaining Files Size: 0 Uploaded Files Count: 0 Uploaded Files Size: 0 Unchanged Files Count: 120 Unchanged Files Size: 3972 Failed Files Size: 0 Failed Files Size: 0 |
Represents the job state
Fields:
Value | Description | Type |
---|---|---|
JobId | Identifies job | string |
SessionState | Identifies current state | enum SessionStateContract: Undefined, |
AccountLogin | Login of account who's running the job | string |
CreatedUtc | When job was created in UTC | DateTime |
StartedUtc | When job started in UTC | DatreTime |
CompletedUtc | When job completed | DateTime, optional |
ProgressPercentage | Execution progress | float |
ErrorMessage | Error details | string |
JobType | enum JobTypeContract: None, |
Represents couint and size of files
Fields:
Value | Description | Type |
---|---|---|
Count | Number of files | long |
SizeBytes | Size of files in bytes | long |
Save Online Backup settings to the settings storage
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Settings | Online backup settings with includes:
| OnlineBackupSettingsContract |
Output fields (SetOnlineBackupSettingsResponse):
Parameter | Description | Type / Validation Rules |
---|---|---|
IsWarning | If cleanup of existing settings was not succeed New settings do not apply to the database in this case | bool |
WarningDetails | Description of warnings during cleanup procedure | string |
Faults:
MethodCallFailed
Parameter | Description | Type / Validation Rules |
---|---|---|
IncludedDirs | Array of FilesetDirContract List of directories to include to backupset | FilesetDirContract |
IncludedFiles | Array of FilesetFileContract List of files to include to backupset | FilesetFileContract |
Excludes | Array of FilesetExcludeItemContract List of filesystem items (files or folders) to exclude from backupset | FilesetExcludeItemContract |
Parameter | Description | Type / Validation Rules |
---|---|---|
Path | Path to backupset directory. If directory located on the mapped drive, use full network path. | string |
Parameter | Description | Type / Validation Rules |
---|---|---|
Path | Path to backupset file. If file located on the mapped drive, use full network path. | string |
Parameter | Description | Type / Validation Rules |
---|---|---|
Path | Path to filesystem item, which will been skipped during backup. No difference betwen excluded file or excluded directory. | string |
Parameter | Description | Type / Validation Rules |
---|---|---|
RemoteName | Remote name of the network share (remote path) | string |
Credentials | Credentials for access to the Network share | CredentialsContract |
Get Online Backup settings from the settings storage
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Output fields (GetOnlineBackupSettingsResponse):
Parameter | Description | Type / Validation Rules |
---|---|---|
Settings | Online backup settings with includes:
| OnlineBackupSettingsContract |
Faults:
MethodCallFailed
Remove existing Online Backup settings from the settings storage
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Output fields (RemoveOnlineBackupSettingsResponse):
Parameter | Description | Type / Validation Rules |
---|---|---|
IsWarning | Only if ResetExistingSettings is set true, if cleanup of existing settings was not succeed New settings do not apply to the database in this case | bool |
WarningDetails | Description of warnings during cleanup procedure | string |
Faults:
MethodCallFailed
Add new Online Backup job request using existing settings
Input fields:
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Configuration | Configuration of the new backup job | OnlineBackupJobContract |
Output fields: RunOnlineBackupJobResponse (Nested from JobSessionContract)
Faults:
MethodCallFailed
Parameter | Description | Type / Validation Rules |
---|---|---|
WindowsUser | Name of the current windows user. Is required to impersonate from user of the backup service to get access to all user files | string |
CallingProcessName | Name of the process, which running under requested windows user rights. Is required to impersonate from user of the backup service. As usual, this is the CurrentProcess.Name of the assembly, which calling SDK | string |
EndTime | Time, when backup service should cancel current backup. When is reached, backup service completing current part of backup and safely cancel backup. If not set - no time limit for completion of backup. | DateTime |
Other filelds | Is not implemented yet |
Backup engine reports about some operations, such as new backup request, starting of the calculation of the files hashes, skipping excluded files, issues etc.
This events is collected in the engine and after that SDK reports. Due to report threshold SDK can report about several events in the one callback.
Parameter | Description | Type / Validation Rules |
---|---|---|
EventTime | Time of event | DateTime |
MessageType | Type of the message
| MessageTypeContract |
Message | Event message | String |
This event is sent in the BackupStarted and BackupProgress callbacks.
In the BackupCompleted callback this event include whole backup summary report.
Parameter | Description | Type / Validation Rules |
---|---|---|
FailedFiles | Quantity and size of files, which was failed | CountAndSizeContract |
UploadedFiles | Quantity and size of files, which was uploaded to server | CountAndSizeContract |
UnchangedFiles | Quantity and size of files, which have not changed since last backup | CountAndSizeContract |
TotalFiles | Total quantity and size of all processed and failed files | CountAndSizeContract |
BackupSetFiles | Total quantity and size of files, included to current backup procedure | CountAndSizeContract |
ModifiedFiles | Quantity and size of files, which was modified since last backup | CountAndSizeContract |
FileStates | Array of the FileStateContract. This files is in progress right now. Array, because backup can process several files simultaneously. Existing just for show 'small' progress, shows only files, processed right now, without collecting of whole history. Some files can be excluded from this array, if they was completed between collection ticks. | FileStateContract |
Parameter | Description | Type / Validation Rules |
---|---|---|
Name | Name of file | string |
Status | Description of the file status (localized) | string |
TotalSizeBytes | Total size of file, bytes | long |
CompletedSizeBytes | Completed size, bytes | long |
Pause the current backup session.
Pausing the current backup session, regardless of who launched it.
If there are other requests for backup in the queue, they will be paused too.
In the absence of active sessions, the Pause does nothing.
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Resume the current backup session (if paused).
Resume the current backup session after pausing, regardless of who launched/paused it.
In the absence of active sessions, the Resume does nothing.
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |
Cancel the current backup session.
Cancels the current backup session, regardless of who launched it.
If there are other requests for backup in the queue, they will be executed immediately after the current session is canceled.
In the absence of active sessions, the Cancel does nothing.
Parameter | Description | Type / Validation Rules |
---|---|---|
Identity | identity object with valid token | IdentityContract |