Nodos y Atributos del Esquema de Servicio Web

Una operación de Servicio Web de Entrada REST invoca un único objeto basado en esquema, ya sea un Objeto de Negocio, un Servicio de Negocio o un Script de Servicio. El objeto tiene un esquema que, por defecto, actúa como esquema de Solicitud y de Respuesta. El producto ofrece la posibilidad de definir un esquema explícito para una operación de servicio web que representa una visualización del esquema interno subyacente para un consumidor externo. Tenga en cuenta que el esquema de operación es una visualización estricta del esquema interno y, como tal, no implementa cambios estructurales.

Si bien es opcional, definir un esquema de operación tiene los siguientes beneficios:

  • Permite declarar si el uso de un elemento parte del esquema de Solicitud, del esquema de Respuesta, de ambos o de ninguno.

  • Permite asignar un nombre de elemento externo a un elemento interno. Esto es útil para evitar la clonación de servicios internos con este único fin.

  • Permite mejorar la administración y visibilidad de las referencias de la operación GET.

  • Permite soportar estructuras de estilo HATEOAS fuera del esquema interno. Esto permite un procesamiento interno ininterrumpido.

  • Permite proporcionar un texto de ayuda para elementos individuales.

La siguiente documentación es una lista completa de los atributos disponibles al construir un esquema de operación de Servicio Web de Entrada.

Contenido

Definición de Esquema de Operación

Elementos Especializados

Especificación de OpenAPI

Definición de Esquema de Operación

Los siguientes atributos definen el esquema de operación externo que establece el esquema de solicitud y de respuesta para la operación.

Mnemotécnico Valores Válidos Descripción Ejemplos
usage= "REQ"

Indica que el elemento debe incluirse únicamente en el esquema de solicitud.

Cuando se especifica para un elemento de lista o grupo, el valor se aplica a todo el contenedor. Un elemento específico del contenedor puede sustituir el valor por defecto del contenedor.

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

Indica que el elemento debe incluirse únicamente en el esquema de respuesta.

Cuando se especifica para un elemento de lista o grupo, el valor se aplica a todo el contenedor. Un elemento específico del contenedor puede sustituir el valor por defecto del contenedor.

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

Indica que el elemento debe incluirse en las definiciones de esquema de solicitud y de respuesta. Éste es el valor por defecto

Cuando se especifica para un elemento de lista o grupo, el valor se aplica a todo el contenedor. Un elemento específico del contenedor puede sustituir el valor por defecto del contenedor.

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

Indica que el elemento no debe incluirse ni en la definición del esquema de solicitud ni en la de respuesta.

Cuando se especifica para un elemento de lista o grupo, el valor se aplica a todo el contenedor. Un elemento específico del contenedor puede sustituir el valor por defecto del contenedor.

 
<httpMethod usage="EXCL" />
mapTo= "internal element name"

Mapea un elemento de servicio web a un elemento interno. Por defecto, se asume que el nombre del elemento interno es igual al nombre del elemento de servicio web. Utilice este atributo para asignar un nombre de elemento externo en el esquema de operación y mapearlo a un elemento interno correspondiente.

Tenga en cuenta que esta no es una expresión XPath, sino una referencia a un nombre de elemento válido que corresponde a la estructura del esquema interno expandido.

El propietario del elemento debe ser igual al propietario del esquema de servicio web. Si se amplió el esquema subyacente de una operación (mediante la extensión del área de datos dinámica), el propietario que realiza la extensión solamente puede hacer referencia a los elementos en la extensión de esquema de servicio web para la operación.

Elemento de esquema interno:

<toDoPriority .../>

Elemento del esquema de operación:

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

Establece una estructura de grupo que representa una clave foránea de una entidad.

El elemento no existe en el esquema interno. Agrupa los elementos de valor de clave foránea junto con un elemento _​link correspondiente que, en tiempo de ejecución, proporciona el URL de punto final de la operación GET de esa entidad. Los consumidores del servicio web pueden utilizar el enlace para obtener los datos de la entidad.

Elemento de esquema interno:

<user .../>

Grupo de esquemas 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 que hacen referencia a una lista de servicios internos.

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

Por defecto, todos los elementos de la lista de referencia se incluyen en el esquema de operación. Puede mencionar y definir explícitamente atributos para elementos específicos según sea necesario.

Elemento de esquema interno:

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

Grupo de esquemas de operación:

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

"expression"

Componentes de la expresión:

  • mo:’<maintenance object>’;

  • pk1:<relative xpath to an element in the internal schema>;

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

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

Solo es válido en los elementos _​self y _​link. El atributo se usa para hacer referencia a la operación GET por defecto de una entidad según lo definido por su objeto de mantenimiento o su objeto de negocio.

La aplicación determina la operación GET que se debe utilizar de la siguiente manera:

  • Si el objeto de negocio de la entidad hace referencia a una operación que utiliza la opción Operación GET, se utiliza esa opción.

  • Si el objeto de mantenimiento de la entidad hace referencia a una operación que utiliza la opción Operación GET, se utiliza esa opción.

  • Si se encuentra una operación GET que hace referencia al objeto de mantenimiento, se utiliza esa opción.

Si no se puede determinar una operación GET para la entidad, se devuelve un texto standard que indica que no hay un enlace disponible.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

"expression"

Componentes de la expresión:

  • iws:’<inbound web service name>’;

  • operation:’<operation name>’;

  • parms:[<external reference as defined on the GET operation record>:<relative xpath of an element name in the internal schema that holds the value>; <another external reference name>:<another relative xpath>;...];

Solo es válido 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 redactar los parámetros de ruta de acceso.

 
<_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 del standard Hypermedia as the Engine of Application State, HATEOAS (Hipermedia como Motor del Estado de la Aplicación). Estos elementos solo deben ser definidos por el esquema de operación, ya que no son relevantes para el servicio de operación interno ni deben ser administrados por este.

En la siguiente lista, se describe cada elemento y cómo se utiliza.

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

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

Este es un elemento opcional y solo puede existir uno en un esquema de operación.

Consulte los atributos de definición de esquema getOperation= para obtener más información.

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

Las cargas útiles de respuesta pueden incluir claves foráneas y, para esas entidades, la respuesta incluye un elemento "_​link" que contiene el URL de punto final de la operación GET para esa entidad (si existe).

Consulte los atributos de definición de esquema role= y getOperation= para obtener más información.

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

Proporciona una referencia standard a una lista de entidades en el esquema interno.

Consulte los atributos de definición de esquema role="COLL" para obtener más información.

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

Atributos de Documentación

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

Mnemotécnico Valores Válidos Descripción Ejemplos
helpText= "help text field name"

Asocia un elemento con un registro de texto de ayuda específico definido para el Servicio Web de Entrada. Si el elemento está incluido en el esquema de solicitud y en el de respuesta, se utiliza el mismo texto de ayuda en ambos.

Si no se especifica este atributo y existe un solo registro de Campo de Texto de Ayuda para el Campo asociado con el elemento interno, se utiliza ese registro de texto de ayuda. Si existe más de un registro de Campo de Texto de Ayuda, se utiliza aquel en el que el nombre del texto de ayuda es igual al nombre del Campo.

Tenga en cuenta que un elemento interno está asociado con un nombre de Campo a través de los atributos mdField=, si existen, o a través del atributo mapField=.

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

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

En este ejemplo, el servicio web de entrada define un campo de texto de ayuda llamado "TD_​ENTRY" que proporciona texto de ayuda para este elemento. Se incluye el mismo texto de ayuda para el elemento tanto en el esquema de solicitud como en el de respuesta.
helpTextResponse= "help text field name"

Asocia un elemento que está incluido en el esquema de solicitud y en el esquema 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 de entrada define los siguientes registros de texto de ayuda:

  • El nombre del campo de texto de ayuda "TD_​ENTRY" describe el elemento enviado en el esquema de solicitud.

  • El nombre del campo de texto de ayuda "TD_​ENTRY_​RESP" describe el elemento completado en el esquema de respuesta.