Mappage des ressources REST aux noms BOD (Business Object Document)

Les services REST sont intégrés sur les services OAGIS. Chaque ressource REST est mappée à un nom BOD (Business Object Document). Un fichier de configuration XML est fourni pour effectuer une transformation entre un nom BID et des données REST. La structure des services REST utilise ensuite ce fichier de configuration pour générer des données de réponse REST à partir d'un objet BOD et construire un objet BOD à partir de données de requête REST.

Par défaut, les fichiers de configuration XML sont packagés sous le répertoire suivant : Rest.war/WEB-INF/config/bodMapping

Les noms de fichier doivent être au format suivant : rest-resourceName-clientobjects.xml. Ils utilisent le même schéma que le Centre de gestion.

Pour plus d'informations, consultez les exemples de fichiers de configuration suivants :

Le fragment XML suivant montre un exemple de mappage entre un nom et une mappe de données REST :


<!-- Product summary data -->
<_config:URLParameterGroup name="productSummary" 1 noun="CatalogNavigationView">
     <_config:IncludeURLParameterGroup urlParameterGroup="price" 2 />
     <_config:IncludeURLParameterGroup urlParameterGroup="facet" />
     <_config:IncludeURLParameterGroup urlParameterGroup="breadCrumbTrail" />
     <_config:IncludeURLParameterGroup urlParameterGroup="previewReport" />
     <_config:IncludeURLParameterGroup urlParameterGroup="suggestion" />
     <_config:IncludeURLParameterGroup urlParameterGroup="webContent" />

     <_config:URLParameter name="recordSetComplete" nounElement="/Show/@recordSetCompleteIndicator" 3
              key="false" return="true" />
     <_config:URLParameter name="recordSetTotal" nounElement="/Show/@recordSetTotal" 
              key="false" return="true" />
     <_config:URLParameter name="recordSetCount" nounElement="/Show/@recordSetCount" 
              key="false" return="true" />
     <_config:URLParameter name="recordSetStartNumber" nounElement="/Show/@recordSetStartNumber" 
              key="false" return="true" />

     <_config:URLParameter name="CatalogEntryView/productType" 4
              nounElement="/CatalogEntryView/@CatalogEntryTypeCode" 5
              key="false" 6 return="true" 7 />

     <_config:URLParameter name="CatalogEntryView/buyable" nounElement="/CatalogEntryView/@buyable" 
              key="false" return="true" />
     <_config:URLParameter name="CatalogEntryView/uniqueID" nounElement="/CatalogEntryView/UniqueID" 
              key="true" return="true" />
     <_config:URLParameter name="CatalogEntryView/partNumber" nounElement="/CatalogEntryView/PartNumber" 
              key="false" return="true" />

     ......
     <!-- UserData Section -->
     <_config:URLParameter name="x_" nounElement="/UserData/UserDataField" return="true" type="UserData" 8 />
</_config:URLParameterGroup>

Où :

1 nom URLParameterGroup: Le nom du groupe de paramètres d'URL. Les services REST s'appuient sur ce groupe et les paramètres URLParameters qui s'y trouvent pour effectuer le mappage.
2 IncludeURLParameterGroupurlParameterGroup: Indique un groupe de paramètres d'URL déclaré à inclure dans le groupe de paramètres d'URL en cours. Les noms des paramètres d'URL des groupes de paramètres d'URL inclus seront fusionnés afin de décrire un nom de paramètre d'URL complet pour le mappage d'élément ou d'attribut de nom.
3 nounElement pour l'objet Afficher: L'élément ou attribut de l'objet Afficher avec lequel la valeur doit être associée. Pour mapper à un élément, utilisez le format nounElement="/ElementName". Pour mapper à un attribut, utilisez le format nounElement="/ElementName/@AttributeName".
4 nom URLParameter: Nom du paramètre d'URL. Il deviendra une clé dans la mappe des données REST.
5 nounElement pour objet de nom: L'élément ou attribut de l'objet de nom avec lequel la valeur doit être associée. Pour mapper à un élément, utilisez le format nounElement="/ElementName". Pour mapper à un attribut, utilisez le format nounElement="/ElementName/@AttributeName".
6 touche: Facultatif : Identificateur unique du nom ou type complexe du nom. La valeur par défaut est false.
7 retour: Facultatif : Indique si l'élément Noun doit être inclus dans la réponse lors de la génération de l'objet réponse. La valeur par défaut est false sauf si la valeur de l'attribut key est true.
8 type: Facultatif : Type de données de l'élément ou de l'attribut de nom. Si la valeur de UserData est indiquée, le mappage du paramètre d'URL revêt une signification particulière et le nom du paramètre d'URL commence par l'attribut de nom indiqué. Les paramètres d'URL de type UserData où le nom de l'élément fait partie du nom du paramètre d'URL ont un comportement d'analyse syntaxique propre. Le nom et la valeur sont mappés sur un nouvel objet, comme indiqué par l'attribut nounElement. Vous pouvez également indiquer l'élément UserDataAssociation pour un mappage d'objet plus complexe.

Un nom peut avoir une structure de données imbriquée. A l'aide du fichier de mappage XML, chaque élément de nom est mappé à un attribut de données REST et le nom est converti en mappe afin que les données REST puissent être facilement analysées par les applications client. La plupart des éléments de nom seront convertis en entrées dans une mappe aplatie. Toutefois, si un élément de nom est une liste, cette zone de données sera convertie en une liste de mappe. Par exemple, avec l'élément OrderItem étant une liste dans le nom Order, les services REST créeront automatiquement liste de mappe pour OrderItem :


<_config:URLParameter name="orderItem/orderItemId" nounElement="/OrderItem/OrderItemIdentifier/UniqueID" key="true" return="true" />
<_config:URLParameter name="orderItem/externalOrderItemID" nounElement="/OrderItem/OrderItemIdentifier/ExternalOrderItemID" key="false" return="true" />
<_config:URLParameter name="orderItem/productId" nounElement="/OrderItem/CatalogEntryIdentifier/UniqueID" key="false" return="true" />

Vous pouvez créer un fichier de configuration d'extension pour remplacer le mappage de données par défaut. Vous devez créer une version personnalisée du fichier dans un nouveau dossier. La version personnalisée du fichier ne doit contenir que les propriétés modifiées.

La procédure suivante est également applicable lorsque vous générez un nouveau service REST à l'aide du modèle de ressource JET. Dans ce cas, vous créez votre propre fichier rest-resourceName-clientobjects.xml pour effectuer une transformation entre votre nom BOD et vos données REST.

Procédure

Ouvrez HCL Commerce Developer et basculez vers la vue Explorateur d'entreprise.
Créez un fichier de mappage de données personnalisé (rest-resourceName-clientobjects.xml), si aucun n'existe déjà :
1. Accédez au chemin suivant :
  Rest.war/WEB-INF/config
2. Sous le dossier config, créez un nouveau dossier bodMapping-ext de sorte que son chemin d'accès soit similaire à ceci :
  Rest.war/WEB-INF/config/bodMapping-ext
  Si ce dossier existe déjà et qu'il contient une version personnalisée du fichier rest-resourceName-clientobjects.xml, ouvrez ce fichier et passez à l'étape 4.
3. Créez un fichier rest-resourceName-clientobjects.xml vide dans le dossier Rest.war/WEB-INF/config/bodMapping-ext. Ce fichier est votre fichier rest-resourceName-clientobjects.xml personnalisé.
Ajoutez les éléments XML de base requis pour votre fichier rest-resourceName-clientobjects.xml personnalisé.
Ajoutez le fichier XML pour toutes les propriétés que vous souhaitez modifier dans votre fichier personnalisé rest-resourceName-clientobjects.xml :
1. Naviguez jusqu'au fichier de configuration par défaut à l'emplacement suivant :
  Rest.war/WEB-INF/config/bodMapping/rest-resourceName-clientobjects.xml
  Ne modifiez pas les propriétés directement dans ce fichier, car vos modifications seraient écrasées pas les mises à jour ultérieures des produits IBM.
2. Copiez les éléments XML des propriétés du fichier de configuration de composant de catalogue par défaut que vous souhaitez modifier vers votre fichier rest-resourceName-clientobjects.xml personnalisé.
  Même si vous ne copiez que certains éléments, vous devez conserver leur hiérarchie XML dans le fichier.
3. Modifiez les valeurs nécessaires.
  Ajout d'un attribut :
```
<_config:URLParameter name="householdSize" nounElement="/PersonalProfile/HouseholdSize" key="false" return="true" />
```
  Suppression d'un attribut :
```
<_config:URLParameter name="companyName" nounElement="/PersonalProfile/CompanyName" key="false" return="false" />
```
4. Inclure les données utilisateur :
  UserData doit avoir un préfixe x prédéterminé et l'élément XML URLParameter doit également avoir une valeur attribute type="UserData". Par exemple, dans le fichier rest-cart-clientobjects.xml, la valeur URLParameter suivante est mappée directement à toutes les données UserData sous OrderItem :
```
<_config:URLParameter name="orderItem/xitem_" nounElement="/OrderItem/UserData/UserDataField" 
key="false" return="true" type="UserData"/>
```
  Si vous créez les 2 paires de clés/valeurs suivantes :
```
expiration=01012012
return=30d
```
  Les services REST renvoient ces 2 éléments de UserData, ainsi que d'autres zones de données, dans le fichier de mappage BOD. La valeur key est ajoutée à xitem_ pour identifier le contexte de UserData. Vous pouvez suivre cette convention pour obtenir toutes les données UserData des services REST :
```
{
"xitem_expiration" : "01012012",
"xitem_return" : "30d"
}
```
  Remarque : UserData se dirige automatiquement vers les services REST tant que le fichier de mappage BOD dispose d'un élément URLParameter pour renvoyer les données userData.
Sauvegardez et fermez le fichier de configuration personnalisé.
Testez vos changements de configuration.

Que faire ensuite

Lorsque vous personnalisez le fichier wc-rest-resourceconfig.xml pour utiliser un profil d'accès différent, si le nouveau profil d'accès renvoie le nom avec des zones de données supplémentaires qui ne sont pas définies dans le fichier XML de mappage BOD, vous devez étendre le fichier XML de mappage BOD pour renvoyer des attributs supplémentaires dans le nouveau profil d'accès :

Créez un fichier de mappage de données personnalisé (rest-resourceName-clientobjects.xml) sous le répertoire Rest.war/WEB-INF/config/bodMapping-ext. Ce fichier est votre fichier rest-resourceName-clientobjects.xml personnalisé.
Déterminez la valeur URLParameterGroup pour les zones de données supplémentaires. Par exemple :
```
<_config:URLParameterGroup name="productSummary" noun="CatalogNavigationView">
```
Ajoutez des attributs de données supplémentaires sous URLParameterGroup.
Redémarrez votre serveur HCL Commerce pour que la personnalisation prenne effet.