Nodos y atributos de esquema de servicio web

Una operación de servicio web entrante (IWS) de REST llama a un objeto basado en esquema único, ya sea un objeto de negocio, un servicio de negocio o un script de servicio. El objeto dispone de un esquema que, por defecto, actúa tanto como esquema de solicitud como de respuesta. El producto ofrece la posibilidad de definir un esquema explícito para una operación de servicio web, que representa una vista del esquema interno subyacente para un consumidor orientado al exterior. Debe tenerse en cuenta que el esquema de operación representa una vista estricta del esquema interno y, como tal, no introduce cambios estructurales.

Aunque es opcional, la definición de un esquema de operación aporta las ventajas siguientes:

  • Declarar el uso de un elemento como parte del esquema de solicitud, de respuesta, de ambos o de ninguno. 

  • Asignar un nombre de elemento externo a un elemento interno. Resulta de utilidad para evitar clonar servicios internos únicamente con este fin.

  • Obtener una mejor gestión y visibilidad de las referencias de la operación GET.

  • Soportar estructuras de estilo HATEOAS fuera del esquema interno. Esto permite un procesamiento interno fluido.

  • Incluir textos de ayuda para elementos individuales.

En la siguiente documentación se incluye una lista completa de los atributos disponibles al construir el esquema de operación de IWS.

Contenido

Definición de esquema de operación

Elementos especializados

Especificación de API abierta

Definición de esquema de operación

Los atributos siguientes definen el esquema de operación orientado al exterior, que establece el esquema de solicitud y el de respuesta para la operación.

Abreviación nemotécnica Valores válidos Descripción Ejemplos
usage= "REQ"

Indica que el elemento debe incluirse en exclusiva en el esquema de solicitud.

Si se especifica para un elemento de un grupo o una lista, el valor se aplicará a todo el contenedor. Se podrá sustituir el valor por defecto del contenedor para un elemento específico.

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

Indica que el elemento debe incluirse en exclusiva en el esquema de respuesta.

Si se especifica para un elemento de un grupo o una lista, el valor se aplicará a todo el contenedor. Se podrá sustituir el valor por defecto del contenedor para un elemento específico.

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

Indica que el elemento deberá incluirse tanto en las definiciones del esquema de solicitud como de respuesta. Es el valor por defecto

Si se especifica para un elemento de un grupo o una lista, el valor se aplicará a todo el contenedor. Se podrá sustituir el valor por defecto del contenedor para un elemento específico.

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

Indica que elemento no se puede incluir en las definiciones del esquema de solicitud ni de respuesta.

Si se especifica para un elemento de un grupo o una lista, el valor se aplicará a todo el contenedor. Se podrá sustituir el valor por defecto del contenedor para un elemento específico.

 
<httpMethod usage="EXCL" />
mapTo= "nombre de elemento interno"

Asigna un elemento de servicio web a un elemento interno. Por defecto, se asume que el nombre del elemento interno será igual que el del elemento de servicio web. Utilice este atributo para asignar un nombre de elemento orientado al exterior en el esquema de operación y asígnelo al elemento interno correspondiente.

Debe tenerse en cuenta que no se trata de una expresión de XPath, sino una referencia a un nombre de elemento válido que corresponde a la estructura del esquema interno ampliado.

El propietario del elemento debe ser igual que el del esquema del servicio web. Si se ha ampliado el esquema subyacente de una operación (mediante una ampliación del área de datos dinámica), el propietario de la ampliación puede hacer referencia en exclusiva a sus propios elementos de la ampliación del esquema de servicio web para la operación.

Elemento de esquema interno:

<toDoPriority .../>

Elemento de esquema de operación:

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

Establece una estructura de grupo que representa una clave externa para una entidad.

El elemento en sí no existe en el esquema interno. Se agrupa con los elementos de valor de clave externa, junto con el correspondiente elemento _​link que, en tiempo de ejecución, ofrece la URL de punto final de la operación GET de la entidad. Los consumidores del servicio web pueden utilizar el enlace para obtener los datos para la entidad.

Elemento de esquema interno:

<user .../>

Grupo de esquema de operación:

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

Establece una estructura de grupo que representa una recopilación de entidades correspondientes a una lista de servicios interna.

El elemento en sí no existe en el esquema interno. Agrupa la lista interna asignada a un elemento _​data, junto con el correspondiente elemento _​link que, en tiempo de ejecución, proporciona la URL de punto final para la operación GET de la recopilación. Los consumidores del servicio web pueden utilizar el enlace para obtener un juego de información más detallada para cada entidad de la lista.

Por defecto, todos los elementos de la lista de referencia se incluyen en el esquema de operación. Se puede hacer referencia explícita a atributos para elementos específicos y definirlos según convenga.

Elemento de esquema interno:

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

Grupo de esquema de operación:

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

“expresión”

Componentes de expresión:

  • mo:’<objeto de mantenimiento>’;

  • pk1:<XPath relativa a un elemento de esquema interno>;

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

Los parámetros pk2–5 son necesarios para establecer la coincidencia con la definición de clave primaria del objeto de mantenimiento.

Solo son válidos en los elementos _​self y _​link. El atributo se utiliza para hacer referencia por defecto a la operación GET de una entidad, según lo definen el objeto de mantenimiento o el objeto de negocio.

La aplicación determina qué operación GET se utilizará de la siguiente manera:

  • Si el objeto de negocio de la entidad hace referencia a una operación utilizando la opción Operación GET, será la que se utilice.

  • Si el objeto de mantenimiento de la entidad hace referencia a una operación utilizando la opción Operación GET, será la que se utilice.

  • Si se encuentra una operación GET que hace referencia al objeto de mantenimiento, será la que se utilice.

Si no se puede determinar una operación GET para la entidad, aparecerá en su lugar un texto estándar que indica que no hay disponible ningún enlace.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

“expresión”

Componentes de expresión:

  • iws:’<nombre de servicio web entrante>’;

  • operation:’<nombre de operación>’;

  • parms:[<referencia externa según se define en el registro de operación GET>:<XPath relativa de un nombre de elemento del esquema interno que incluye el valor>; <otro nombre de referencia externa>:<otra XPath relativa>;...];

Solo son válidos en los elementos _​self y _​link. El atributo se utiliza para hacer referencia a una operación GET específica, junto con la información necesaria para componer los parámetros de ruta.

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

Elementos especializados

La definición del esquema de operación utiliza nombres de elementos especializados en el estilo de hipermedia como estándar de motor de estado de aplicación (HATEOAS). Estos elementos solo se pueden definir en el esquema de operación, ya que no son relevantes para el servicio de operación interno ni se pueden gestionar en este.

En la siguiente lista se describe cada elemento y el modo de uso.

Nombre de elemento Descripción Ejemplos
<_​self .../>

Las cargas útiles de respuesta pueden incluir un elemento "_​self" que contiene la URL de punto final de la operación GET relacionada con la entidad devuelta en la respuesta.

Se trata de un elemento opcional y solo puede existir uno en un esquema de operación.

Para obtener más información, consulte los atributos de definición de esquema getOperation=.

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

Las cargas útiles de respuesta pueden incluir claves externas para estas entidades; la respuesta incluirá un elemento "_​link" que contiene la URL de punto final de la operación GET de dicha entidad (si existe).

Para obtener más información, consulte los atributos de definición de esquema role= y getOperation=.

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

Incluye una referencia estándar a una lista de entidades del esquema interno.

Para obtener más información, consulte el atributo de definición de esquema role=”COLL”.

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

Atributos de documentación

Los atributos siguientes proporcionan documentación adicional para elementos individuales que se incluyen como parte de la especificación de API abierta del servicio web.

Abreviación nemotécnica Valores válidos Descripción Ejemplos
helpText= “nombre de campo de texto de ayuda”

Asocia un elemento con un registro de texto de ayuda específico definido para el servicio web entrante. Si el elemento se incluye tanto en el esquema de solicitud como de respuesta, se utilizará el mismo texto de ayuda para ambos.

Si no se especifica este atributo y solo existe un único registro de campo de texto de ayuda para el campo asociado con el elemento interno, se utilizará dicho registro de texto de ayuda. Si existe más de un registro de campo de texto de ayuda, se utilizará el que tenga el mismo nombre de texto de ayuda que el campo.

Tenga en cuenta que el elemento interno se asocia a un nombre de campo mediante el atributo mdField=, si existe, o mapField=, si no.

No es válido para elementos _​self ni _​link.

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

En este ejemplo, un servicio web entrante define un nombre de campo de texto de ayuda “TD_​ENTRY” que incluye el texto de ayuda para este elemento. Se incluirá el mismo texto de ayuda para el elemento tanto en el esquema de solicitud como de respuesta.
helpTextResponse= “nombre de campo de texto de ayuda”

Asocia un elemento que se incluye tanto en el esquema de solicitud como de respuesta, con un registro de texto de ayuda específico que se utilizará en el contexto del esquema de respuesta.

Sigue las mismas reglas que el atributo helpText=.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
En este ejemplo, el servicio web entrante define los siguientes registros de texto de ayuda:

  • El nombre del campo de texto de ayuda “TD_​ENTRY” describe el elemento que se envía en el esquema de solicitud.

  • El nombre de campo de texto de ayuda “TD_​ENTRY_​RESP” describe el elemento que se rellena en el esquema de respuesta.