API nsapi

Aperçu technique

L’API du logiciel permet à des applications tierces de se connecter au serveur de sauvegarde et de réaliser des tâches d’administration et de contrôle en exposant un très grand nombre de fonctionnalités du produit sous forme de classes COM/OLE Automation.

La technologie OLE Automation est incluse dans toutes les versions de Windows et définit un standard binaire d’interopérabilité entre les programmes. Elle est exploitable dans les langages de scripting intégrés à Windows (JScript, VBScript) et depuis tous les langages supportant le standard COM (C++, C#, PHP, Delphi...).

L’API est compilée sous la forme d’une serveur COM "out-of-process", c'est à dire d'un exécutable natif démarré par Windows quand une application tierce se connecte au service de scripting. Le processus implémentant l'API possède son propre espace d'adressage et n'est pas chargé dans l'espace mémoire du processus appelant.

L’API est installée et enregistrée lors du déploiement du produit. Aucune opération supplémentaire n’est nécessaire pour l’utiliser si le logiciel (client ou serveur) a été correctement installé sur le poste. Elle est composée de deux modules :

  • L’API dite "serveur", dont il est question dans cette documentation, qui permet d’effectuer toutes les tâches nécessitant un accès au serveur de sauvegarde. Elle couvre une très grande partie des fonctionnalités exposées par le logiciel, et peut être autant exploitée par un profil "utilisateur" (gestion des tâches, déclenchement des sauvegardes, exploration des données sauvegardées) que par un profil "administrateur" (gestion des utilisateurs, contrôle des alertes, création de plan d’exécution, etc.).
  • L’API dite "cliente", qui ne permet que de manipuler certains composants de l’agent client, et dont l’aide est disponible ici. Ce composant est installé uniquement avec l’agent client et ne sera pas détaillé sur cette page.

Si votre langage supporte l’utilisation directe d’objets Automation et de l'interface IDispatch ("late-binding"), il est conseillé d’utiliser cette méthode pour ne pas dépendre d’une quelconque version de l’API (la résolution des types étant réalisée lors de l’exécution de l’application).

Nous fournissons également les fichiers "type library" (*.TLB) dans le répertoire d’installation du logiciel ("nsapi.tlb" pour l'API serveur, "nsclientapi.tlb" pour l'API cliente), qui peuvent être utilisés pour importer les informations de type dans votre langage de développement favori. Référez-vous à l’aide des outils de développement que vous utilisez pour obtenir plus d’informations sur l’importation et l’utilisation de fichiers TLB.

Types COM utilisés

L'API utilise les types COM de base suivants :

  • __int64 : entier signé 64 bit.
  • VARIANT_BOOL : type booléen.
  • BSTR : chaîne de caractère COM Unicode.
  • long : entier signé 32 bit.
  • VARIANT : type COM "VARIANT", généralement utilisé pour stocker des dates.

Le logiciel utilise abondamment le type __int64 pour identifier de manière unique les objets stockés sur le serveur de sauvegarde. VBScript ne supportant pas les entiers codés sur 64 bits, la classe NsScriptUtils propose des fonctions utilitaires pour certains langages ne supportant pas l'intégralité des types COM utilisés.

Sauf mention contraire, toutes les dates sont encodées au format GMT (universel). Lorsque vous affichez des dates, vous devriez les convertir au format local, en ajoutant à la date GMT le décalage du fuseau horaire en vigueur (la classe NsScriptUtils prend également en charge cette fonctionnalité si besoin).

Philosophie générale

Chaque classe COM exposée représente un objet géré par le système de sauvegarde. La liste des classes disponibles est affichée dans la partie supérieure gauche de cette page ("Classes"). L’API expose également certains type énumérés, affichés dans la partie inférieure de cette page ("Enums"). Si vous importez les informations de type depuis le fichier nsapi.tlb, ces types énumérées devraient être automatiquement convertis sous forme de déclarations de constantes compatibles avec votre langage.

Lorsqu’une classe est instanciée, elle ne représente qu’un conteneur de données déconnecté du serveur. Aussi, les méthodes d’instance qui requièrent un échange de données avec le serveur de sauvegarde exigent qu’un objet de type NsConnection correctement initialisé et connecté soit passé en paramètre. L'objet est utilisé pour envoyer une requête réseau au serveur de sauvegarde et analyser la réponse reçue.

Toute fonction effectuant un appel de procédure distant renvoit un type booléen servant à détecter si l’opération a pu se dérouler avec succès sur le serveur. Si une erreur a été renvoyée par le serveur durant l’exécution de la dernière commande, le code de l’erreur est stocké dans le champ ErrorCode de l’objet NsConnection.

En général, tout objet est identifié par un numéro unique sur 64 bit qui peut être utilisé pour charger l'élément, lorsque la méthode LoadFromID() est implémentée. Celle-ci prend en paramètre le numéro unique de l’objet ainsi que l’objet NsConnection à utiliser pour effectuer l’appel de procédure distant. Lorsqu’un objet est chargé avec succès, ses propriétés sont initialisées et vous pouvez commencer à interagir avec l’élément.

Lorsque vous modifiez les propriétés d’un objet, les données sont mises à jour en mémoire mais doivent être ensuite appliquées sur le serveur en utilisant la méthode Update(), qui prends en paramètre un objet NsConnection initialisé sur le serveur de sauvegarde distant. Certaines constantes numériques possèdent un sens particulier. Par exemple, la valeur (__int64) -1 doit être affectée au champ ID d'un objet à créer sur le serveur via sa méthode Update().

De manière assez évidente, les propriétés marquées "read-only" dans la documentation ne sont pas modifiables par code, il s’agit d’indicateurs maintenus par le serveur que vous pouvez uniquement lire.

Lorsque les objets peuvent être supprimés du serveur, ils implémentent généralement une méthode Delete prenant en paramètre un objet NsConnection actif. Lorsqu'un objet a été supprimé, il reste manipulable comme objet du langage mais toute opération nécessitant une connexion au serveur échouera - l'objet n'étant plus référencé dans la base de données du logiciel.

Voici un code VBScript illustrant le chargement d'un objet NsBackup, étant donné que "TheID" représente l’identifiant unique d’une sauvegarde à modifier, et "TheConnection" une connexion initialisée sur le serveur de sauvegarde :

' Créer un objet COM de type "NsBackup"
set backup = CreateObject("NsAPI.NsBackup")
' Tenter de charger la sauvegarde en utilisant un identifiant fourni en paramètre
if backup.LoadFromID(TheConnection, TheID) then
  ' La sauvegarde est correctement chargée. Modifier le mode de comparaison - utiliser les hashs des fichiers :
  backup.CompareMode = nsCompareFileHashes
  ' Mettre à jour la sauvegarde
  if backup.Update(TheConnection) then
  begin
    ' Succès
    MsgBox "La sauvegarde a été mise à jour avec succès"
  end else
    ' Echec
    MsgBox "Impossible de mettre à jour la sauvegarde, avez-vous assez de droits ?"
  end
else
  ' Erreur de chargement
  MsgBox "Impossible de charger la sauvegarde n°“ + TheID + “, vérifiez qu’elle existe bien sur le serveur de sauvegarde."
end if

Gestion des connexions

Etant donné que l’API serveur exige une connexion entre votre programme et le serveur de sauvegarde une des première choses que vous aurez besoin de faire consistera à ouvrir une session via l’objet NsConnection. Cette classe exige que vous lui fournissiez les paramètres d’accès au serveur de sauvegarde ainsi que les paramères d’authentification du profil utilisateur à exploiter. La section "Exemples" de la classe NsConnection présente deux exemples de connexions, l’une à un serveur local, l’autre à un serveur distant. Notez que l'API ne permet pas d'accèder aux paramètres de connexion configurés par l'utilisateur si elle est utilisée depuis un poste sur lequel l'agent client est installé. Vous devrez donc demander ces informations à l'utilisateur ou les stocker "en dur" dans votre programme.

Suivant le profil utilisateur exploité lors de l’ouverture de la session, l’appel de certaines méthodes peut échouer et certaines fonctionnalités peuvent être totalement indisponible. Ainsi, les fonctionnalités relatives à l’administration du serveur de sauvegarde (création/suppression d’utilisateurs, de groupes, consultation de l’historique des opérations et des journaux serveur... et plus globalement tout accès à des objets n’appartenant pas à l’utilisateur actif) ne seront pas exploitables par un profil d’utilisateur standard. Pour savoir si les droits administrateurs vous ont été attribués lors de la connexion, consultez le champ IsAdmin de l’objet NsConnection.

Le champ Me de l’objet NsConnection pointe vers un objet NsUser représentant le profil utilisateur courant lorsqu’une connexion a été initiée avec succès sur le serveur de sauvegarde. Cet objet donne accès aux données attachées à l’utilisateur : sauvegardes (NsBackup), fichiers partagés (NsSharedFile), etc.

Pour avoir accès à tous les objets gérés par le serveur en tant qu'administrateur, instanciez un objet de type NsServer, appelez la méthode Load() et accèdez ensuite ses méthodes et ses propriétés

.

Collections COM

Les listes d’objets sont implémentés sous la forme de collection COM implémentant l’interface IEnumVariant. Cela vous permet d’itérer dans les collections à l’aide de constructions de type for each collectionVar in collectionList. Les collections comportent toutes une propriété Count renvoyant le nombre total d’éléments stockés, ainsi qu’une méthode Item prenant un entier index en paramètre renvoyant l’objet de la liste à l’index passé en paramètre.

Généralement, les collections contiennent des éléments correspondant à des objets du serveur de sauvegarde, et nécessitent d’être chargés en utilisant un objet NsConnection connecté au serveur. Par exemple, les sauvegardes associées à un utilisateur (NsUser) ne sont pas chargées lors de l’initialisation de l’objet, au contraire, elles sont récupérées uniquement lors de l’appel de la méthode Backups(), qui renvoie une liste de type NsBackupCollection et qui prends en paramètre l’objet NsConnection utilisé pour effectuer l’appel de procédure distant.