Définition de services z/OS Connect
Les définitions de service z/OS® Connect fournissent le mécanisme d'accès aux actifs de l'application z/OS à l'aide d'appels REST. Pour activer ces services, vous devez ajouter une définition de service z/OS Connect au fichier server.xml de Liberty en indiquant le nom d'élément zosConnectService ainsi qu'un nom d'élément de référence et un fournisseur de service.
Pourquoi et quand exécuter cette tâche
Les services z/OS Connect sont définis par l'élément de configuration zosConnectService. Cet élément contient des définitions d'attributs pouvant avoir des contreparties définies au niveau global. Des attributs peuvent être définis globalement via l'élément zosConnectManager . Ces attributs, s'ils ont été définis, s'appliquent à tous les services. Si des attributs globaux tout comme des attributs au niveau du service ont été définis, les valeurs définies au niveau zosConnectService sont utilisées.
z/OS Connect fournit une implémentation de service qui permet aux requêtes z/OS Connect d'interagir avec des actifs z/OS via WOLA (WebSphere Optimized Local Adapters). Le service est automatiquement activé lorsque les fonctions zosConnect-1.0 et zosLocalAdapters-1.0 sont toutes deux configurées. Des instances de ce service peuvent être définies via l'élément de configuration localAdaptersConnectService.
z/OS Connect fournit également une implémentation de service autorisant les demandes z/OS Connect à contacter des noeuds finaux REST distants. Le service est disponible quand la fonction zosConnect-1.2 est configurée. Des instances de ce service peuvent être définies via l'élément de configuration zosConnectServiceRestClient. Pour plus d'informations, voir la documentation relative au service de client REST z/OS Connect.
Procédure
- Ajoutez un élément de configuration zosConnectService pour chaque service dans votre configuration server.xml. Vous devez configurer au minimum les attributs serviceRef et serviceName. L'élément serviceRef pointe vers l'élément de configuration du fournisseur de services. L'attribut serviceName est ce par quoi le fournisseur de services s'identifie auprès de z/OS Connect et représente également le nom à utiliser comme partie de l'URL pour les requêtes z/OS Connect ciblant un service spécifique. Le nom de service doit être unique.
Ci-après figure un exemple de fichier
server.xml illustrant comment ajouter un service z/OS Connect nommé recordOpsCreate. Un exemple plus complet est montré à l'étape 3.
Pour en savoir plus sur les définitions d'attributs configurables associées à l'élément zosConnectService, voir la documentation de la fonction z/OS Connect.<!-- z/OS Connect service definitions --> <zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreate"/>
- (Facultatif) Ajoutez l'élément de configuration zosConnectManager au fichier server.xml.
Cet élément est un singleton dans le fichier de configuration server.xml et contient des valeurs globales qui s'appliquent à tous les services z/OS Connect définis pour le serveur. L'élément peut contenir les noms d'intercepteurs z/OS Connect ou d'éléments de configuration de fournisseur de transformation des données qui s'appliquent à tous les services du serveur.
L'exemple suivant décrit un élément de configuration zosConnectManager définissant un groupe d'opérations nommé Operator1 sous l'élément globalOperationsGroup. Il s'agit du nom du groupe de sécurité (SAF ou LDAP) auquel doit être rattaché l'ID du client demandeur pour que des demandes d'opérations z/OS Connect (telles que action=start|stop|status) puissent être autorisées. Ce groupe s'applique à tous les services dans les configurations z/OS Connect. L'entrée dataxform définit le nom d'élément où z/OS Connect trouvera un fournisseur de transformation de données. L'entrée dataxform dans l'élément zosConnect indique qu'il s'agit d'une implémentation de fournisseur de transformation pour tous les services dans la configuration qui n'ont pas encore leur propre référence d'élément de transformation de données. L'entrée interceptors est le nom de l'élément dans la configuration qui décrit le jeu d'intercepteurs z/OS Connect qui s'appliquent à tous les services dans la configuration.
<zosConnectManager id="zosConnectGlobals" globalOperationsGroup="Operator1" globalDataxformRef="XformJSON2Byte" globalInterceptorsRef="GlobalInterceptors"/>
Pour en savoir plus sur les définitions d'attributs configurables associées à l'élément zosConnectManager, voir la documentation de la fonction z/OS Connect.
Pour plus d'informations sur chaque attribut, reportez-vous à la documentation des fonctions Liberty. - Si WOLA est configuré dans Liberty, la configuration d'une demande requiert un élément de configuration localAdaptersConnectService dans le fichier server.xml. Cette configuration est composée au minimum du nom de la fabrique de connexions WOLA, du nom de registre et du nom du service. La configuration de z/OS Connect suit les conventions Liberty en requérant uniquement de spécifier les paramètres minimum. Notez que lorsque vous configurez une fabrique de connexions WOLA pour interaction avec z/OS Connect, vous devez utiliser un conteneur comme mécanisme d'authentification. Les fabriques de connexions WOLA qui ne spécifient pas un attribut containerAuthDataRef ne sont pas prises en
charge. Voici un exemple :
<!-- Local adapters connection factory definition --> <authData id="cauth1" user="user1" password="{xor}LDo8Ki02KyY="/> <connectionFactory id="wolaCF" jndiName="eis/ola" containerAuthDataRef="cauth1" > <properties.ola/> </connectionFactory> <!-- Local adapters config --> <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="LIBERTY" wolaName3="LIBERTY" /> <!-- WOLA Connect service and z/OS Connect service definitions --> <localAdaptersConnectService id="wolaOpsCreate" registerName="BATCH01" serviceName="COBLPGM1" connectionFactoryRef="wolaCF"/> <zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreate" runGlobalInterceptors="true" interceptorsRef="serviceInterceptorList" dataXformRef="zconXform"/> <!-- z/OS Connect data transformer --> <zosConnectDataXform id="zconXform" bindFileLoc="/zosConnect/bind" bindFileSuffix=".bnd" requestSchemaLoc="/zosConnect/schema" responseSchemaLoc="/zosConnect/schema" requestSchemaSuffix=".json" responseSchemaSuffix=".json"> </zosConnectDataXform>
L'implémentation du service z/OS Connect qui permet aux requêtes z/OS Connect d'interagir avec des actifs z/OS via WOLA (WebSphere Optimized Local Adapters) peut nécessiter un transformateur de données. Si un transformateur de données a été configuré, globalement ou au niveau du service, les charges utiles en entrée et en sortie sont converties au moyen de ce transformateur. Si un transformateur de données n'a pas été configuré et que la demande contient un contenu JSON, le service suppose que le programme dorsal se chargera de la conversion des données. Le service convertit le contenu JSON en tableau d'octets en utilisant l'encodage spécifié dans l'en-tête de la demande ou l'encodage de JSON par défaut (UTF-8). De la même manière, si l'actif renvoie un contenu et qu'aucun transformateur de données n'a été configuré, l'implémentation du service WOLA s'attend à recevoir un contenu JSON sous forme de tableau d'octets, lequel est converti en contenu de réponse JSON d'après les mêmes règles d'encodage que celles utilisées pour transformer un contenu de demande JSON en tableau d'octets.
Lorsque linkTaskChanID est configuré avec le réglage useCICSContainer=true sous l'élément localAdaptersConnectService, un ensemble de conteneurs de contexte et un conteneur de contenu sont envoyés au programme de destination. La liste suivante fournit le nom et la description de chaque conteneur de contexte :- ZCONReqURL
- Le conteneur de contexte ZCONRegURL contient l'URL de la demande HTTP. Par exemple, si la définition invokeURI utilisée est /banking/deposit et le paramètre de requête, country=USA, l'URL sera https://localhost:port/banking/deposit?country=USA.
- ZCONReqQParms
- Le conteneur de contexte ZCONReqQParms contient les paramètres de requête de la demande HTTP. Par exemple, dans l'URL de demande https//localhost:port//banking/deposit?country=USA, le paramètre de requête est country=USA.
- ZCONReqMethod
- Le conteneur de contexte ZCONReqMethod contient la méthode de la demande HTTP. Par exemple, GET.
- ZCONHTTPHeaders
- Le conteneur de contexte ZCONHTTPHeaders contient un ensemble au format JSON de paires nom/valeur d'en-tête HTTP configurées au moyen de l'attribut linkTaskChanCtxContHttpHeaders sous l'élément localAdaptersConnectService.
Les utilisateurs peuvent changer l'encodage par défaut des données (cp819) contenues dans tous les conteneurs de contexte en utilisant l'attribut de configuration linkTaskChanCtxContEncoding sous l'élément localAdaptersConnectService.
Lorsque linkTaskChanID est configuré, accompagné du réglage useCICSContainer=true sous l'élément localAdaptersConnectService, vous pouvez personnaliser les noms des charges utiles des conteneurs en entrée et en sortie en utilisant les attributs linkTaskChanReqContID et linkTaskChanRespContID. Si ces attributs ne sont pas définis, les noms par défaut sont ZCONReqData et ZCONRespData. L'exemple suivant illustre une configuration correcte.<localAdaptersConnectService id="wolaOpsCreate" registerName="OLASERVER" serviceName="ZCONMC5" connectionFactoryRef="wolaCF" linkTaskChanID="ZCONCHANNEL" linkTaskChanType="1" useCICSContainer="true" linkTaskChanCtxContHttpHeaders="Connection, CustomHeader1, CustomHeader2, CustomHeader3" linkTaskChanReqContID="wolaOpsReqData" linkTaskChanRespContID="wolaOpsRespData" linkTaskChanCtxContEncoding="cp037"/>
Le tableau suivant contient une liste de définitions d'attributs localAdaptersConnectService et une description de chacun.
Définition d'attribut Description serviceName
required="true"
type="String"
Nom du service WOLA cible. La valeur de l'attribut serviceName doit être identique au nom qu'une application à espace d'adressage externe utilise pour le nom du service sur une demande WOLA Receive ou un appel d'API de service hôte, ou encore au nom de programme utilisé pour SVC avec un serveur de liaison WOLA CICS. registerName
required="true"
type="String"
Nom de l'enregistrement cible WOLA. Ce nom doit correspondre au nom qu'une application d'espace adresse externe utilise pour le nom de registre sur un appel API WOLA Register, ou au nom utilisé pour RGN avec un serveur CICS Link Server WOLA. La valeur de registerName peut être n'importe quelle chaîne alphanumérique de 1 à 12 caractères. connectionFactoryRef
required="true"
type="String"
Référence à la fabrique de connexions de l'adaptateur de ressource WOLA configuré. connectionWaitTimeout
required="false"
type="Integer"
min="0"
max="2147483647"
Durée d'attente en secondes jusqu'à ce qu'une application d'espace adresse externe correspondant au nom d'enregistrement émette une API WOLA Receive Request ou Host Service et devienne active. Cet attribut définit la propriété ConnectionWaitTimeout pour la fabrique de connexions des adaptateurs locaux optimisés. Si sa valeur n'est pas spécifiée, la valeur par défaut de la propriété est utilisée. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskTranID
required="false"
type="String"
Définit le nom de l'ID de transaction de la tâche d'appel de liaison du serveur CICS Link Server WOLA (toute chaîne de 4 caractères). Cet attribut est utilisé lors de l'utilisation du serveur CICS Link Server. Cet attribut définit la propriété LinkTaskTranID pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. useCICSContainer
required="false"
type="Boolean"
default="false"
Définit le mécanisme à utiliser pour la propagation des données. Lorsque cet attribut est à 'true', le contenu est passé au programme d'application CICS cible à l'aide des conteneurs CICS. S'il est à 'false' (sa valeur par défaut), le contenu est passé au programme d'application CICS cible à l'aide d'une zone de communication (COMMAREA). Cet attribut est utilisé lors de l'utilisation du serveur CICS Link Server. Cet attribut définit la propriété useCICSContainer pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskReqContType
type="Integer"
min="0"
default="0"
Définit le type de conteneur de demande (0=CHAR, 1=BIT). Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskReqContID et useCICSContainer (true) sont également configurés. Cet attribut définit la propriété linkTaskReqContType pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskRspContID
required="false"
type="String"
Définit le nom du conteneur de réponse ou de sortie (chaîne de 1 à 16 caractères qui correspond au nom de conteneur déclaré à CICS). Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskReqContID et useCICSContainer (true) sont également configurés. Cet attribut définit la propriété linkTaskRspContID pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskRspContType
type="Integer"
min="0"
default="0"
Définit le type du conteneur de réponse (0=CHAR, 1=BIT). Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskRspContID et useCICSContainer (true) sont également configurés. Cet attribut définit la propriété linkTaskRspContType pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskChanID
required="false"
type="String"
Définit le nom du canal CICS à utiliser pour la livraison et la réception des contenus avec les conteneurs CICS (chaîne de 1 à 16 caractères qui correspond au nom de canal déclaré à CICS). Cet attribut est utilisé lorsque CICS Link Server est utilisé et lorsque l'attribut useCICSContainer (true) est également configuré. Cet attribut définit la propriété linkTaskChanID pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskChanType
required="false"
type="Integer"
min="0"
default="0"
Définit le type de conteneurs CICS (0=CHAR, 1=BIT) associé à l'ID de canal configuré. Lorsque cet attribut est mis à 0=CHAR (sa valeur par défaut), l'encodage attendu/retourné pour les données de type caractères dans les conteneurs d'entrée/de sortie est ASCII (CCSID 819), et les données sont converties vers/depuis l'encodage EBCDIC (cp037) avant/après leur envoi vers/depuis le programme de destination. Utilisez le type BIT pour éviter qu'un encodage ou un type de données particulier ne soit attendu. Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskChanID et useCICSContainer (true) sont également configurés. Cet attribut définit la propriété linkTaskChanType pour la fabrique de connexions des adaptateurs locaux optimisés. Pour plus d'informations, référez-vous à la documentation des propriétés de la fabrique de connexions pour les adaptateurs locaux optimisés sur Liberty. linkTaskChanReqContID
required="false"
default="ZCONReqData"
type="String"
Définit le nom du conteneur de demande (chaîne de 1 à 16 caractères qui correspond au nom de conteneur déclaré à CICS). Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskChanID et useCICSContainer (true) sont également configurés.
linkTaskChanRespContID
required="false"
default="ZCONRespData"
type="String"
Définit le nom du conteneur de réponse (chaîne de 1 à 16 caractères qui correspond au nom de conteneur déclaré à CICS). Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskChanID et useCICSContainer (true) sont également configurés.
linkTaskChanCtxContEncoding
required="false"
type="String"
default="cp819"
Définit l'encodage des données dans tous les conteneurs de contexte envoyés au programme de destination. Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskChanID et useCICSContainer (true) sont également configurés.
linkTaskChanCtxContHttpHeaders
required="false"
type="String"
Définit le nom d'en-tête HTTP ou la liste des noms d'en-tête HTTP séparés par des virgules qui sont passés au programme de destination avec le conteneur de contexte dont le nom est ZCONHTTPHeaders. Les informations contenues dans ce conteneur de contexte sont au format JSON : {httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}}. Cet attribut est utilisé lorsque CICS Link Server est utilisé et que les attributs linkTaskChanID et useCICSContainer (true) sont également configurés.

Nom du fichier : twlp_zconnect_srvcdef.html