Atributos e Nós do Esquema do Serviço Web

Uma operação de serviço Web de entrada REST (IWS) chama um único objeto baseado em esquema, seja um Objeto de Negócios, um Serviço de Negócios ou um Script de Serviço. O objeto tem um esquema que, por padrão, atua como o esquema Solicitação e Resposta. O produto permite definir um esquema explícito para uma operação de serviço Web que representa uma exibição do esquema interno subjacente para um consumidor externo. Observe que o esquema de operação é uma exibição estrita do esquema interno e, como tal, não introduz alterações estruturais.

Embora opcional, a definição de um esquema de operação tem os seguintes benefícios:

  • Declarando o uso de um elemento sobre se ele faz parte do esquema de Solicitação, do esquema de Resposta, ambos ou nenhum deles.

  • Atribuição de um nome de elemento externo a um elemento interno. Útil para evitar a clonagem de serviços internos somente para essa finalidade.

  • Melhor gerenciamento e visibilidade das referências de operação GET.

  • Dê suporte a estruturas de estilo HATEOAS fora do esquema interno. Isso permite o processamento interno contínuo.

  • Fornecer texto de ajuda para elementos individuais.

A documentação a seguir contém uma lista completa dos atributos disponíveis ao criar um esquema de operação do IWS.

Definição do Esquema de Operação

Os atributos a seguir definem o esquema de operação externa que estabelece a solicitação e o esquema de resposta para a operação.

Mnemônico Valores Válidos Descrição Exemplos
uso= "REQ"

Indica que o elemento deve ser incluído somente no esquema de solicitação.

Quando especificado para um elemento de grupo ou de lista, o valor se aplica a todo o contêiner. Um elemento específico no contêiner pode substituir o padrão do contêiner.

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

Indica que o elemento deve ser incluído somente no esquema de resposta.

Quando especificado para um elemento de grupo ou de lista, o valor se aplica a todo o contêiner. Um elemento específico no contêiner pode substituir o padrão do contêiner.

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

Indica que o elemento deve ser incluído nas definições de esquema de solicitação e resposta. Esse é o valor padrão

Quando especificado para um elemento de grupo ou de lista, o valor se aplica a todo o contêiner. Um elemento específico no contêiner pode substituir o padrão do contêiner.

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

Indica que o elemento não deve ser incluído nas definições do esquema de solicitação ou resposta.

Quando especificado para um elemento de grupo ou de lista, o valor se aplica a todo o contêiner. Um elemento específico no contêiner pode substituir o padrão do contêiner.

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

Mapeia um elemento de serviço Web para um elemento interno. Por padrão, o nome do elemento interno é considerado igual ao nome do elemento do serviço Web. Use este atributo para atribuir um nome de elemento de face externa no esquema de operação e mapeá-lo para um elemento interno correspondente.

Observe que essa não é uma expressão XPath, mas uma referência a um nome de elemento válido que corresponde à estrutura do esquema interno expandido.

O proprietário do elemento deve ser igual ao proprietário do esquema de serviço Web. Se o esquema subjacente de uma operação foi estendido (usando extensão de área de dados dinâmica), o proprietário estendido só poderá estabelecer referência a seus elementos em sua extensão de esquema de serviço Web para a operação.

Elemento de esquema interno:

<toDoPriority .../>

Elemento do esquema de operação:

<priority mapTo="toDoPriority"/>
função= "FKGP"

Estabelece uma estrutura de grupo que representa uma chave externa para uma entidade.

O elemento em si não existe no esquema interno. Ele agrupa os elementos de valor da chave externa com um elemento _​link correspondente que, no tempo de execução, fornece o URL do ponto final da operação GET dessa entidade. Os consumidores do web service podem usar o link para obter os dados da entidade.

Elemento de esquema interno:

<user .../>

Grupo de esquemas de operação:

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

Estabelece uma estrutura de grupo que representa um conjunto de entidades que corresponde a uma lista de serviços internos.

O elemento em si não existe no esquema interno. Ele agrupa a lista interna mapeada para um elemento _​data com um elemento _​link correspondente que, no tempo de execução, fornece o URL do ponto final para a operação GET da coleção. Os consumidores do serviço Web podem usar o link para obter um conjunto mais detalhado de informações para cada entidade na lista.

Por padrão, todos os elementos da lista referenciada são incluídos no esquema de operação. É possível estabelecer referência explícita e definir atributos para elementos específicos, conforme necessário.

Elemento de esquema interno:

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

Grupo de esquemas de operação:

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

"expression"

Componentes da expressão:

  • mo:'<maintenance object>';

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

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

Os parâmetros pk2-5 são necessários para corresponder à definição da chave primária do objeto de manutenção.

Só é válido nos elementos _ self e _ link. O atributo é usado para estabelecer referência à operação GET padrão de uma entidade, conforme definido por seu objeto de manutenção ou objeto de negócios.

O aplicativo determina a operação GET a ser usada da seguinte forma:

  • Se o objeto de negócios da entidade fizer referência a uma operação usando a opção Operação GET, ela será usada.

  • Se o objeto de manutenção da entidade fizer referência a uma operação usando a opção Operação GET, ela será usada.

  • Se for encontrada uma operação GET que faça referência ao objeto de manutenção, ela será usada.

Se não for possível determinar uma operação GET para a entidade, será retornado um texto padrão indicando que um link não está disponível.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

"expression"

Componentes da expressão:

  • 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>;...];

Só é válido nos elementos _ self e _ link. O atributo é usado para estabelecer referência a uma operação GET específica junto com as informações necessárias para compor seus parâmetros de caminho.

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

Elementos Especializados

A definição do esquema de operação usa nomes de elementos especializados no estilo da Hipermídia como o padrão Engine of Application State (HATEOAS). Esses elementos devem ser definidos apenas pelo esquema de operação, uma vez que não são relevantes nem devem ser gerenciados pelo serviço de operação interna.

A lista a seguir descreve cada elemento e como ele é usado.

Nome do Elemento Descrição Exemplos
<_​self .../>

As cargas úteis de resposta podem incluir um elemento "_ self" que contém o URL do ponto final da operação GET relacionada à entidade retornada na resposta.

Este é um elemento opcional e somente um pode existir em um esquema de operação.

Consulte os atributos de definição do esquema getOperation= para obter mais informações.

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

As cargas úteis de resposta podem incluir chaves externas e, para essas entidades, a resposta inclui um elemento "_ link" que contém o URL de ponto final da operação GET para essa entidade (se ela existir).

Para obter mais informações, consulte o atributo de definição de esquema role= e getOperation=.

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

Fornece uma referência padrão a uma lista de entidades no esquema interno.

Para obter mais informações, consulte o atributo de definição de esquema role="COLL".

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

Atributos da Documentação

Os atributos a seguir fornecem documentação adicional para elementos individuais que são incluídos como parte da especificação da API Aberta do serviço Web.

Mnemônico Valores Válidos Descrição Exemplos
helpText= “nome de campo de texto de ajuda”

Associa um elemento a um registro de texto de ajuda específico definido para o serviço Web de Entrada. Se o elemento estiver incluído no esquema de solicitação e resposta, o mesmo texto de ajuda será usado em ambos.

Se esse atributo não for especificado e existir um único registro de Campo de texto de ajuda para o Campo associado ao elemento interno, esse registro de texto de ajuda será usado. Se existir mais de um registro desse campo de texto de ajuda, o nome do texto de ajuda será igual ao nome do campo será usado.

Os consumidores do serviço Web podem usar o link para obter um conjunto mais detalhado de informações para cada entidade na lista.

Não é válido para os elementos de link _ self e _.

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

Neste exemplo, o serviço Web de entrada define um nome de campo de texto de ajuda "TD_​ENTRY" que fornece texto de ajuda para este elemento. O mesmo texto de ajuda está incluído para o elemento no esquema de solicitação e resposta.
helpTextResponse= “nome de campo de texto de ajuda”

Associa um elemento incluído no esquema de solicitação e resposta a um registro de texto de ajuda específico a ser usado no contexto do esquema de resposta.

Segue as mesmas regras do atributo helpText=.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
Neste exemplo, o serviço Web de entrada define os seguintes registros de texto de ajuda:

  • O nome do campo de texto da ajuda "TD_​ENTRY" descreve o elemento enviado no esquema de solicitação.

  • O nome do campo de texto da ajuda "TD_​ENTRY_​RESP" descreve o elemento preenchido no esquema de resposta.