Sommaire
Exposer une méthode
Pour exposer une méthode Python dans Constellation vous devez tout simplement ajouter le décorateur “Constellation.MessageCallback” sur votre méthode :
|
1 2 3 |
@Constellation.MessageCallback() def SimpleMessageCallback(): Constellation.WriteInfo('Hello Python !') |
Ici nous déclarons le MessageCallback “SimpleMessageCallback” sans paramètre ni documentation.
Vous pouvez ajouter un ou plusieurs arguments à votre MC et utiliser la syntaxe de Python pour commenter vos MC :
|
1 2 3 4 5 6 7 8 9 10 11 |
@Constellation.MessageCallback() def DemoArg(data): "Ceci est la description du MessageCallback DemoArg avec 1 argument" Constellation.WriteInfo('arg = %s', data) @Constellation.MessageCallback() def DemoArgs(a, b, c): "Ceci est la description du MessageCallback DemoArgs avec 3 arguments" Constellation.WriteInfo(a) Constellation.WriteInfo(b) Constellation.WriteInfo(c) |
Le ou les paramètres peuvent être des types simples (string, int, bool, etc..) ou des types (objets) complexes :
|
1 2 3 4 5 6 |
@Constellation.MessageCallback() def ComplexMessageCallback(data): "Ceci est la description du MessageCallback ComplexMessageCallback avec un objet complexe en argument" Constellation.WriteInfo(data.A) Constellation.WriteInfo(data.B) Constellation.WriteInfo(data.C) |
L’ensemble de ces méthodes déclarées “MessageCallbacks” seront alors référencées dans la Constellation. Vous pouvez les découvrir en interrogeant le Package Descriptor de votre package.
Par exemple, lancez la Console Constellation et rendez-vous dans le “MessageCallback Browser”. Vous aurez la liste de vos méthodes avec la possibilité de les invoquer directement depuis l’interface :
Documenter son MessageCallback
Description des MessageCallbacks
Comme vous l’avez remarqué dans les exemples précédents, nous utilisons la documentation des méthodes de Python :
|
1 2 3 4 |
@Constellation.MessageCallback() def Demo(): "Ceci est la description du MessageCallback !" pass |
La documentation de la méthode est utilisée comme description du MessageCallback :
La description de la méthode peut être écrite sur plusieurs lignes :
|
1 2 3 4 5 6 7 |
@Constellation.MessageCallback() def Demo(): ''' The first line is brief explanation, which may be completed with a longer one. For instance to discuss about its methods. ''' pass |
Description des arguments des MessageCallbacks
Note : la description des arguments est disponible depuis l’API Python 1.8.4.x. Pensez à mettre à jour la référence de votre API par Nuget depuis Visual Studio ou en mettant à jour le template depuis la CLI.
Si vous regardez attentivement les arguments des MC dans le MessageCallback Explorer, ils sont reconnus comme « System.Object » étant donné que les arguments d’une fonction en Python ne sont pas typés.
Pour décrire les paramètres utilisez la syntaxe suivante dans la description du MC :
|
1 |
:param <type> <name> : <description> |
Par exemple :
|
1 2 3 4 5 6 7 8 9 10 11 12 |
@Constellation.MessageCallback() def Demo(a, b, c): ''' Ceci est un exemple de MC avec 3 parametres :param int a: My int value :param bool b: My boolean value :param string c: My string value ''' Constellation.WriteInfo("a = %s - type: %s" % (a, type(a))) Constellation.WriteInfo("b = %s - type: %s" % (b, type(b))) Constellation.WriteInfo("c = %s - type: %s" % (c, type(c))) |
Ainsi en retournant sur le MC Explorer, chaque argument est correctement typé dans Constellation.
Paramètres optionnels avec valeur par défaut
Vous pouvez également définir que certains paramètres sont optionnels en spécifiant leurs valeurs par défaut avec la syntaxe [default: XXX] :
|
1 2 3 4 5 6 7 8 9 10 |
@Constellation.MessageCallback() def DemoOptional(a, b): ''' Ceci est un exemple de MC des paramètres optionnels :param int a: My int value [default:10] :param bool b: My boolean value [default:true] ''' Constellation.WriteInfo("a = %s" % a) Constellation.WriteInfo("b = %s" % b) |
Décrire les arguments de type complexe
Dans le cas où un MC prend en paramètre un (ou plusieurs) type complexe, il faudra d’abord décrie le type dans la méthode « Start ».
Par exemple, enregistrons au démarrage du package (méthode Start), le type “CredentialInfo” :
|
1 2 3 4 |
Constellation.DescribeMessageCallbackType("CredentialInfo", "Credential information", [ { 'Name':'Username', 'Type':'string', 'Description': 'The username' }, { 'Name':'Password', 'Type':'string', 'Description': 'The password' }, ]) |
Une fois tous vos types déclarés, il faut publier le “Package Descriptor” de votre package à Constellation par la ligne :
|
1 |
Constellation.DeclarePackageDescriptor() |
Nous pouvons maintenant déclarer un MC avec un parametre de type “CredentialInfo”. Par exemple :
|
1 2 3 4 5 6 7 8 |
@Constellation.MessageCallback() def DemoAuth(credential): ''' Demo MC avec avec un paramètre de type complexe :param CredentialInfo credential: the credential info ''' Constellation.WriteInfo("User=%s Password=%s" % (credential.Username, credential.Password)) |
Comme vous pourrez le voir dans le MessageCallbacks Explorer, votre méthode Python est correctement décrite ainsi que son paramètre “credential” de type “Credentialnfo”.
Notez également que la description du type CredentialInfo est accessible en cliquant sur le type :
Personnaliser le MessageCallback
Comme pour l’API.NET, par défaut le nom du MessageCallback déclaré dans la Constellation est le nom de votre méthode mais vous pouvez redéfinir le nom exposé dans la Constellation :
|
1 2 3 |
@Constellation.MessageCallback("MySuperName") def MyInternalMethodName(): Constellation.WriteInfo("Hello") |
Aussi vous pouvez “cacher” ce MessageCallback à la Constellation.
|
1 2 3 4 |
@Constellation.MessageCallback(False) def HiddenMessageCallback(): "Hidden message callback" Constellation.WriteInfo("I'm here !!") |
Tous les packages ou consommateurs de votre Constellation pourront envoyer un message “HiddenMessageCallback” à votre package Python et donc invoquer votre méthode mais celle-ci ne sera pas déclarée dans le “Package Descriptor”.
Récupérer le contexte
Comme avec l’API.NET, vous pouvez récupérer le contexte de réception du message en déclarant comme dernier argument de votre MessageCallback, le paramètre “context”.
Par exemple :
|
1 2 3 4 5 |
@Constellation.MessageCallback("MaMethode") # méthode renommée ! def DemoSeb5(context): "Test du contexte" Constellation.WriteInfo("Sender : %s" % context.Sender.FriendlyName) Constellation.WriteInfo("test sans parametre") |
Ou avec des paramètres :
|
1 2 3 4 5 |
@Constellation.MessageCallback() def DemoSeb5(a, b, context): "Test du contexte avec parametre" Constellation.WriteInfo("Sender : %s" % context.Sender.FriendlyName) Constellation.WriteInfo("a = %s et b = %s" % (a, b)) |
Il faut juste que le dernier argument soit nommé “context”. Notez qu’il ne fait pas partie de la signature de votre MessageCallback.
Ci-dessus, le 1er exemple est un MessageCallback caché et sans paramètre et le 2ème n’a que deux paramètres “a” et “b”.
L’objet “context” correspondant à la classe “Constellation.Package.MessageContext”. Vous retrouvez les propriétés suivantes :
- IsSaga : indique si le message reçu appartient à une Saga
- SagaId : identifiant de la Saga (si IsSaga = true)
- Scope : scope d’envoi du message reçu
- Type : type du scope (All, Group, Package, Sentinel, Others)
- Args : arguments du scope (ex : nom du groupe, du package ou de la sentinelle)
- Sender : représente l’émetteur du message
- ConnectionId : identifiant de connexion unique de l’émetteur
- Type : type de l’émetteur (ConsumerHub, ConstellationHub, ConsumerHttp ou ConstellationHttp)
- FriendlyName : nom de l’émetteur
Répondre aux Sagas
Votre méthode peut également retourner une réponse à l’appelant, c’est ce que l’on appelle une saga. Pour cela vous pouvez spécifier le type de la valeur de retour dans le décorateur de la façon suivante :
|
1 2 3 4 5 |
@Constellation.MessageCallback(returnType='System.Boolean') def DemoSaga(user, password): "Test de saga" Constellation.WriteInfo("User=%s Password=%s" % (user, password)) return user == password |
Cependant il est recommandé d’utiliser la description du MC pour spécifier le type de retour avec la syntaxe
|
1 |
:return <type>: <description> |
Par exemple :
|
1 2 3 4 5 6 7 8 9 10 11 |
@Constellation.MessageCallback() def DemoSaga(user, password): ''' Test de saga :param string user: The username :param string password: The password :return bool: if user match ''' Constellation.WriteInfo("User=%s Password=%s" % (user, password)) return user == password |
Cela marche également en combinant la récupération du contexte :
|
1 2 3 4 5 6 7 8 9 10 11 12 |
@Constellation.MessageCallback() def DemoAuth(user, password, context): ''' Test de saga :param string user: The username :param string password: The password :return bool: if user match ''' Constellation.WriteInfo("Sender : %s" % context.Sender.FriendlyName) Constellation.WriteInfo("User=%s Password=%s" % (user, password)) return user == password |
Par exemple en ouvrant le “Message Callback Explorer” de la Console Constellation vous constaterez que votre MC “DemoAuth” est bien référencé comme retournant un “Booléen” en prenant deux arguments (car l’argument “context” n’est pas pris en compte dans la signature du MC) :
En invoquant cette méthode depuis la console, vous recevrez alors la réponse du package, ici un booléen :
Dans les logs, on retrouve bien la trace de l’invocation de notre Saga avec le “contexte” :
(le FriendlyName de la Console Constellation est “Consumer/ControlCenter:<user>”).
Démarrez la discussion sur le forum Constellation