AddSOAPRequestHeader |
Ajout d'une requête d'entête SOAP |
|---|---|
| Lucee | |
Syntaxe
| AddSOAPRequestHeader( webservice=object, namespace=string, name=string, value=object, mustUnderstand=boolean ); |
Paramètres
| Nom | Description |
|---|---|
| webservice | Ce paramètre permet de spécifier l'objet représentant le service Web SOAP sur lequel l'entête doit être ajouté. Il s'agit généralement d'une référence obtenue après avoir créé ou initialisé une connexion vers un service SOAP. |
| namespace | Ce paramètre permet d'indiquer l'espace de noms XML auquel l'entête SOAP appartient. Il sert à éviter les conflits entre différents éléments en définissant un contexte unique pour l'entête. |
| name | Ce paramètre permet de préciser le nom de l'entête SOAP à insérer. C'est l'identifiant qui sera utilisé par le service Web pour reconnaître et traiter correctement cette information. |
| value | Ce paramètre permet de définir la valeur associée à l'entête SOAP. Elle peut être de type simple (chaîne, nombre, booléen) ou complexe (objet XML ou structure), selon les besoins du service Web. |
| mustUnderstand | Ce paramètre permet d'indiquer si le service Web doit obligatoirement comprendre et traiter cet entête. Si défini à true, le serveur rejettera la requête si l'entête n'est pas reconnu ; si défini à false, l'entête sera considéré comme optionnel. |
Description
Cette fonction permet d'ajouter un entête SOAP à une demande de service Web avant d'effectuer la demande.
Remarques
- La fonction AddSOAPRequestHeader() est indispensable lorsqu'on souhaite enrichir une requête SOAP avec des informations supplémentaires, comme des identifiants d'authentification, des métadonnées ou des paramètres de contexte. Ces entêtes jouent un rôle clef dans la communication entre client et serveur, car ils permettent de transmettre des instructions non directement liées au corps du message, mais essentielles à son interprétation.
- Le paramètre webservice constitue la base de la fonction, puisqu'il désigne l'objet SOAP sur lequel l'entête sera appliqué. Cet objet est généralement obtenu par un appel préalable à CreateObject("webservice", url), initialisant la connexion au service à distance. Sans cette référence valide, la fonction ne saurait savoir à quelle requête attacher les informations, rendant l'opération impossible.
- Le paramètre namespace assure la clarté et la cohérence des éléments XML dans l'entête SOAP. En définissant un espace de noms unique, il évite les ambiguïtés lorsque plusieurs éléments portent le même nom dans des contextes différents. Cela garantit une compatibilité maximale entre systèmes SOAP hétérogènes et renforce la conformité du message avec les standards W3C.
- Le paramètre name correspond au nom précis de l'entête que l'on souhaite insérer dans la requête SOAP. Il s'agit d'un identifiant logique qui sera reconnu par le service destinataire. Une mauvaise définition de ce nom peut entraîner un rejet du message ou une incompréhension de la part du serveur, car chaque service attend souvent des noms d'entêtes spécifiques à sa propre implémentation.
- Le paramètre value offre une grande souplesse puisqu'il peut contenir des données simples (texte, booléen, nombre) ou des structures plus complexes (XML, objets, structures ColdFusion). Cela permet d'adapter les requêtes SOAP à une large variété de protocoles métiers. Par exemple, on peut y inclure des informations d'authentification, des identifiants de session ou même des blocs de configuration spécifiques.
- Le paramètre mustUnderstand est un indicateur crucial dans la communication SOAP. Lorsqu'il est défini à true, il impose au service distant de reconnaître et de traiter l'entête ; sinon, la requête sera refusée. Cette option permet d'imposer des règles de validation strictes, garantissant ainsi la conformité et la sécurité du dialogue entre le client et le serveur.
- L'utilisation de AddSOAPRequestHeader() renforce le contrôle du développeur sur la structure du message SOAP. Elle permet de personnaliser finement la requête avant son envoi, ce qui est particulièrement utile dans des environnements où plusieurs services partagent une même interface, mais exigent des en-têtes différents. Cette flexibilité favorise la réutilisation du code et facilite l'intégration d'API externes complexes.
- Sur le plan technique, AddSOAPRequestHeader() s'avère particulièrement utile dans les scénarios d'interopérabilité entre plateformes. En ajoutant des en-têtes spécifiques, Lucee peut communiquer avec des services développés dans d'autres langages comme Java, .NET ou PHP, tout en respectant les conventions SOAP standardisées. Elle assure ainsi la compatibilité entre différents environnements technologiques sans nécessiter de conversions manuelles.
Dernière mise à jour : Jeudi, le 14 Août 2025