Correlación de recursos REST con nombres BOD (Documento de objeto de negocio)

Los servicios REST se crean sobre servicios OAGIS. Cada recurso REST se correlaciona con un nombre BOD (Documento de objeto de negocio). Se proporciona un archivo de configuración XML para transformar entre un nombre BOD y datos REST. Entonces, la infraestructura de servicios REST utiliza este archivo de configuración para generar datos de respuesta REST a partir de un objeto BOD y construir un objeto BOD a partir de los datos de petición REST.

De forma predeterminada, los archivos de configuración XML se empaquetan en el directorio siguiente: Rest.war/WEB-INF/config/bodMapping

Los nombres de archivo deben estar en el formato siguiente: rest-resourceName-clientobjects.xml. Utilizan el mismo esquema que el Centro de gestión.

Para obtener más información, consulte los archivos de configuración de ejemplo siguientes:

En el fragmento de código XML siguiente se muestra un ejemplo de correlación entre un nombre y una correlación de datos 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>

Donde:

1 Nombre de URLParameterGroup: El nombre del grupo de parámetros URL. Los servicios REST se basan en este grupo y los URLParameters que tienen debajo para realizar la correlación.
2 IncludeURLParameterGroupurlParameterGroup: Especifica un grupo de parámetros URL declarados que se incluirán como parte del grupo de parámetros URL actuales. Los nombres del parámetro URL de los grupos de parámetros URL incluidos se fusionarán para describir un nombre de parámetro URL completo a elemento de nombre y correlación de atributos.
3 nounElement del objeto Show: El elemento o atributo del objeto Show con el que debe asociarse el valor. Para correlacionar con un elemento, utilice el formato nounElement="/ElementName". Para correlacionar con un atributo, utilice el formato nounElement="/ElementName/@AttributeName".
4 Nombre de URLParameter: El nombre del parámetro de URL. Se convertirá en una clave en la correlación de datos REST.
5 nounElement para el objeto noun: El elemento o atributo del objeto noun con el que debe asociarse el valor. Para correlacionar con un elemento, utilice el formato nounElement="/ElementName". Para correlacionar con un atributo, utilice el formato nounElement="/ElementName/@AttributeName".
6 clave: Opcional: El identificador exclusivo del nombre o el tipo completo del nombre. El valor predeterminado es false.
7 devolver: Opcional: Especifica si el elemento de nombre debe incluirse en la respuesta cuando se crea el objeto de respuesta. El valor predeterminado es false a menos que el valor del atributo de clave sea true.
8 tipo: Opcional: El tipo de datos de elemento o atributo de nombre. Si se especifica un valor de UserData, la correlación de parámetros URL tiene un significado especial y el nombre de parámetro URL empieza por el atributo del nombre especificado. Los parámetros URL de tipo UserData donde el nombre del elemento forma parte del nombre de parámetro URL tienen un comportamiento de análisis especial. El nombre y el valor están correlacionados con un objeto nuevo, según lo indicado mediante el atributo nounElement. También puede especificar un elemento UserDataAssociation para una correlación de objetos más compleja.

Un nombre puede tener una estructura de datos anidados. Utilizando el archivo de correlación XML, cada elemento de nombre se correlaciona con un atributo de datos REST y el nombre se convierte en una correlación, de forma que las aplicaciones cliente puedan analizar los datos REST fácilmente. Para la mayoría de los elementos del nombre, se convertirán en entradas en una correlación aplanada. No obstante, si un elemento de nombre es una lista, este campo de datos se convertirá en una lista de correlación. Por ejemplo, si OrderItem es una lista del nombre Pedido, los servicios REST crearán, automáticamente, la Lista de correlación para 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" />

Puede crear un archivo de configuración de extensión para sobrescribir la correlación de datos predeterminada. Debe crear una versión personalizada del archivo en una nueva carpeta, con la versión personalizada del archivo, que solo debe contener las propiedades cambiadas.

El procedimiento siguiente también se aplica cuando se genera un servicio REST nuevo utilizando el patrón de recursos JET. En este caso, creará su propio rest-resourceName-clientobjects.xml para realizar transformaciones entre su nombre BOD y los datos REST.

Procedimiento

Abra HCL Commerce Developer y cambie a la vista Explorador de empresa.
Cree un archivo de correlaciones de datos personalizado (rest-resourceName-clientobjects.xml), si aún no existe ninguno.
1. Navegue hasta la vía de acceso siguiente:
  Rest.war/WEB-INF/config
2. En la carpeta config, cree una nueva carpeta bodMapping-ext de modo que la vía de acceso sea parecida a la siguiente:
  Rest.war/WEB-INF/config/bodMapping-ext
  Si esta carpeta ya existe y contiene una versión personalizada del archivo rest-resourceName-clientobjects.xml, abra el archivo y salte al paso 4.
3. Cree un archivo vacío rest-resourceName-clientobjects.xml en la carpeta Rest.war/WEB-INF/config/bodMapping-ext. Este archivo es el archivo rest-resourceName-clientobjects.xml personalizado.
Añada los elementos XML básicos que son necesarios para el archivo rest-resourceName-clientobjects.xml personalizado.
Añada XML para cualquiera de las propiedades que desee cambiar en el archivo rest-resourceName-clientobjects.xml personalizado:
1. Vaya al archivo de configuración predeterminado en la vía de acceso siguiente:
  Rest.war/WEB-INF/config/bodMapping/rest-resourceName-clientobjects.xml
  No cambie nunca las propiedades directamente en este archivo porque los cambios se sobrescribirán con futuras actualizaciones de software de IBM.
2. Copie los elementos XML para las propiedades que desea cambiar del archivo de configuración de componente predeterminado en el archivo rest-resourceName-clientobjects.xml.
  Aunque esté copiando únicamente determinados elementos, debe mantener la jerarquía XML para aquellos elementos del archivo.
3. Cambie los valores de las propiedades copiadas que sean necesarios.
  Adición de un atributo:
```
<_config:URLParameter name="householdSize" nounElement="/PersonalProfile/HouseholdSize" key="false" return="true" />
```
  Eliminación de un atributo:
```
<_config:URLParameter name="companyName" nounElement="/PersonalProfile/CompanyName" key="false" return="false" />
```
4. Incluya los datos de usuario:
  UserData debe tener un prefijo x predeterminado y el elemento XML URLParameter también debe tener un valor attribute type="UserData". Por ejemplo, en el archivo rest-cart-clientobjects.xml, el URLParameter siguiente se correlaciona con todos los valores Userdata que estén directamente debajo de OrderItem:
```
<_config:URLParameter name="orderItem/xitem_" nounElement="/OrderItem/UserData/UserDataField" 
key="false" return="true" type="UserData"/>
```
  Si crea los 2 pares de clave/valor siguientes:
```
expiration=01012012
return=30d
```
  Los servicios REST devuelven estas 2 partes de UserData junto con otros campos de datos en el archivo de correlación de BOD. Se añade key a xitem_ para identificar el contexto del valor UserData. Puede seguir este convenio para obtener todos los valores UserData de los servicios REST:
```
{
"xitem_expiration" : "01012012",
"xitem_return" : "30d"
}
```
  Nota: Los valores UserData fluyen a los servicios REST automáticamente, siempre y cuando el archivo de correlación BOD tenga un elemento URLParameter para devolver el valor userData.
Guarde y cierre el archivo de configuración personalizado.
Pruebe los cambios de configuración.

Qué hacer a continuación

Cuando personalice archivo wc-rest-resourceconfig.xml para utilizar un perfil de acceso diferente, si el nuevo perfil de acceso devuelve el nombre con campos de datos adicionales que no estén definidos en el archivo XML de correlación de BOD, deberá ampliar el archivo XML de correlación de BOD para que devuelva atributos adicionales en el nuevo perfil de acceso:

Cree un archivo de correlaciones de datos personalizado (rest-resourceName-clientobjects.xml) debajo del directorio Rest.war/WEB-INF/config/bodMapping-ext. Este archivo es el archivo rest-resourceName-clientobjects.xml personalizado.
Decida el valor URLParameterGroup para los campos de datos adicionales. Por ejemplo:
```
<_config:URLParameterGroup name="productSummary" noun="CatalogNavigationView">
```
Añada atributos de datos adicionales debajo del valor URLParameterGroup.
Reinicie el servidor de HCL Commerce para que entre en vigor la personalización.