Noeuds et attributs de schéma de service Web

Une opération de service Web REST entrant appelle un seul objet basé sur un schéma, à savoir un objet métier, un service fonctionnel ou un script de service. L'objet comporte un schéma qui, par défaut, fait office à la fois de schéma de requête et de schéma de réponse. Le produit permet de définir un schéma explicite pour une opération de service Web qui représente une vue du schéma interne sous-jacent pour un client externe. Notez que le schéma d'opération est une vue stricte du schéma interne et qu'en tant que tel, il n'introduit pas de modifications structurelles.

Bien que facultative, la définition d'un schéma d'opération présente les avantages suivants :

  • Déclarer l'utilisation d'un élément pour savoir s'il fait partie du schéma de requête, du schéma de réponse ou des deux.

  • Affecter un nom d'élément externe à un élément interne. Utile pour éviter le clonage de services internes à cette fin uniquement.

  • Améliorer la gestion et de la visibilité des références des opérations GET.

  • Prendre en charge les structures de style HATEOAS en dehors du schéma interne. Cela permet un traitement interne transparent.

  • Fournir un texte d'aide pour des éléments individuels.

La documentation suivante fournit une liste complète des attributs dont vous disposez pour créer un schéma d'opération de service Web entrant.

Définition de schéma d'opération

Les attributs suivants définissent le schéma d'opération externe qui établit le schéma de requête et de réponse pour l'opération.

Mnémonique Valeurs valides Description Exemples
usage= "REQ"

Indique que l'élément doit être inclus dans le schéma de requête uniquement.

Lorsqu'elle est indiquée pour un élément de groupe ou de liste, la valeur s'applique à l'ensemble du conteneur. Un élément spécifique du conteneur peut remplacer la valeur par défaut du conteneur.

 
<customerName usage="REQ" />
"RESP"

Indique que l'élément doit être inclus dans le schéma de réponse uniquement.

Lorsqu'elle est indiquée pour un élément de groupe ou de liste, la valeur s'applique à l'ensemble du conteneur. Un élément spécifique du conteneur peut remplacer la valeur par défaut du conteneur.

 
<customerId usage="RESP" />
"BOTH"

Indique que l'élément doit être inclus dans les définitions de schéma de requête et de réponse. C'est la valeur par défaut

Lorsqu'elle est indiquée pour un élément de groupe ou de liste, la valeur s'applique à l'ensemble du conteneur. Un élément spécifique du conteneur peut remplacer la valeur par défaut du conteneur.

 
<customerName usage="BOTH" />
"EXCL"

Indique que l'élément ne doit pas être inclus dans les définitions de schéma de requête ou de réponse.

Lorsqu'elle est indiquée pour un élément de groupe ou de liste, la valeur s'applique à l'ensemble du conteneur. Un élément spécifique du conteneur peut remplacer la valeur par défaut du conteneur.

 
<httpMethod usage="EXCL" />
mapTo= "nom d'élément interne"

Mappe un élément de service Web sur un élément interne. Par défaut, le nom de l'élément interne est supposé être identique au nom de l'élément de service Web. Utilisez cet attribut pour affecter un nom d'élément externe dans le schéma d'opération et le mapper sur un élément interne correspondant.

Il ne s'agit pas d'une expression XPath, mais plutôt d'une référence à un nom d'élément valide qui correspond à la structure du schéma interne étendu.

Le propriétaire de l'élément doit être identique au propriétaire du schéma de service Web. Si le schéma sous-jacent d'une opération a été étendu (à l'aide de l'extension de zone de données dynamique), le propriétaire de l'extension peut uniquement référencer ses éléments dans son extension de schéma de service Web pour l'opération.

Elément de schéma interne :

<toDoPriority .../>

Elément de schéma d'opération :

<priority mapTo="toDoPriority"/>
role= "FKGP"

Etablit une structure de groupe qui représente une clé étrangère pour une entité.

L'élément lui-même n'existe pas dans le schéma interne. Il regroupe les éléments de la valeur de clé étrangère ainsi qu'un élément _​link correspondant qui, lors de l'exécution, fournit l'URL d'adresse complète de l'opération GET de cette entité. Les clients du service Web peuvent utiliser le lien pour obtenir les données de l'entité.

Elément de schéma interne :

<user .../>

Groupe de schéma d'opération :

<user role="FKGP">
   <user>
   <_link getOperation="mo:'USER';pk1:user;"/>
</user>
"COLL"

Etablit une structure de groupe qui représente un ensemble d'entités correspondant à une liste de services internes.

L'élément lui-même n'existe pas dans le schéma interne. Il regroupe la liste interne mappée sur un élément _​data et un élément _​link correspondant qui, lors de l'exécution, fournit l'URL d'adresse complète pour l'opération GET de l'ensemble. Les clients du service Web peuvent utiliser ce lien pour obtenir un ensemble plus détaillé d'informations pour chaque entité de la liste.

Par défaut, tous les éléments de la liste référencée sont inclus dans le schéma d'opération. Vous pouvez explicitement référencer et définir des attributs pour des éléments spécifiques si nécessaire.

Elément de schéma interne :

<alerts type="list">
     <alert/>
     <startDate />
     <endDate />
     <version />
   </_data> </alerts>

Groupe de schéma d'opération :

<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
        <version usage="EXCL"/>
   </_data>
</alerts>
getOperation=

"expression"

Composants d'expression :

  • mo:'<objet de maintenance>';

  • pk1:<xpath relatif d'un élément du schéma interne>;

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

Les paramètres pk2-5 sont requis pour correspondre à la définition de clé primaire de l'objet de maintenance.

Valide uniquement sur les éléments _ self et _ link. L'attribut est utilisé pour référencer l'opération GET par défaut pour une entité telle que définie par son objet de maintenance ou son objet métier.

L'application détermine l'opération GET à utiliser comme suit :

  • Si l'objet métier de l'entité référence une opération à l'aide de l'option Opération GET, cette opération est utilisée.

  • Si l'objet de maintenance de l'entité référence une opération à l'aide de l'option Opération GET, cette opération est utilisée.

  • Si une opération GET référençant l'objet de maintenance est trouvée, cette opération est utilisée.

Si une opération GET ne peut pas être déterminée pour l'entité, un texte standard indiquant qu'aucun lien n'est disponible est renvoyé.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

"expression"

Composants d'expression :

  • iws:'<nom de service Web entrant>';

  • operation:'<nom de l'opération>';

  • parms:[<référence externe telle que définie dans l'enregistrement d'opération GET>:<xpath relatif d'un nom d'élément dans le schéma interne qui contient la valeur>; <autre nom de référence externe>:<autre xpath relatif>;...];

Valide uniquement sur les éléments _ self et _ link. L'attribut est utilisé pour référencer une opération GET spécifique avec les informations nécessaires pour composer ses paramètres de chemin.

 
<_self getOperation="iws:'F1-ToDoEntry'; operation:'getToDoEntry'; parms:[toDoEntryId:toDoEntryId;]"/>

Eléments spécialisés

La définition du schéma d'opération utilise des noms d'élément spécialisés dans le style de la norme Hypermedia comme moteur de l'état de l'application (HATEOAS). Ces éléments ne doivent être définis que par le schéma d'opération car ils ne sont pas pertinents pour le service d'opération interne et ne doivent pas être gérés par le celui-ci.

La liste suivante décrit chaque élément et son utilisation.

Nom de l'élément Description Exemples
<_​self .../>

Les charges utiles de réponse peuvent inclure un élément "_ self" qui contient l'URL d'adresse complète de l'opération GET associée à l'entité renvoyée dans la réponse.

Il s'agit d'un élément facultatif et un seul peut exister dans un schéma d'opération.

Pour plus d'informations, voir les attributs de définition de schéma getOperation=.

 
<_self getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​link .../>

Les charges utiles de réponse peuvent inclure des clés étrangères. Pour ces entités, la réponse inclut un élément "_ link" qui contient l'URL d'adresse complète de l'opération GET pour cette entité (si elle existe).

Pour plus d'informations, voir les attributs de définition de schéma role= et getOperation=.

 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>
<_​data .../>

Fournit une référence standard à une liste d'entités dans le schéma interne.

Pour plus d'informations, voir l'attribut de définition de schéma role="COLL".

 
<alerts role="COLL">
   <_link getOperation="... "/>
   <_data mapTo="alerts">
   </_data>
</alerts>

Attributs de documentation

Les attributs suivants fournissent une documentation supplémentaire pour les éléments individuels inclus dans la spécification OpenAPI du service Web.

Mnémonique Valeurs valides Description Exemples
helpText= "nom du champ de texte d'aide"

Associe un élément à un enregistrement de texte d'aide spécifique défini pour le service Web entrant. Si l'élément est inclus à la fois dans le schéma de requête et de réponse, le même texte d'aide est utilisé dans les deux.

Si cet attribut n'est pas spécifié et qu'un seul enregistrement de champ de texte d'aide existe pour le champ associé à l'élément interne, cet enregistrement de texte d'aide est utilisé. S'il existe plusieurs enregistrements de champ de texte d'aide, celui dans lequel le nom du texte d'aide est identique au nom du champ est utilisé.

Notez qu'un élément interne est associé à un nom de champ via les attributs mdField=, le cas échéant, sinon via l'attribut mapField=.

Non valide pour les éléments _ self et _ link.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY"/>

Dans cet exemple, le service Web entrant définit un nom de champ de texte d'aide "TD_​ENTRY" qui fournit un texte d'aide pour cet élément. Le même texte d'aide est inclus pour l'élément dans le schéma de requête et de réponse.
helpTextResponse= "nom du champ de texte d'aide"

Associe un élément inclus dans le schéma de requête et de réponse à un enregistrement de texte d'aide spécifique à utiliser dans le contexte du schéma de réponse.

Suit les mêmes règles que l'attribut helpText=.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
Dans cet exemple, le service Web entrant définit les enregistrements de texte d'aide suivants :

  • Le nom de champ de texte d'aide "TD_​ENTRY" décrit l'élément envoyé dans le schéma de requête.

  • Le nom de champ de texte d'aide "TD_​ENTRY_​RESP" décrit l'élément renseigné dans le schéma de réponse.