Węzły i atrybuty schematu usługi internetowej

Operacja przychodzącej usługi internetowej REST wywołuje pojedynczy obiekt oparty na schemacie, obiekt biznesowy, usługę biznesową lub skrypt usługi. Obiekt ma jeden schemat, który domyślnie działa zarówno jako schemat żądania, jak i odpowiedzi. Produkt umożliwia zdefiniowanie jawnego schematu operacji usługi internetowej, który reprezentuje widok podstawowego schematu wewnętrznego dla konsumenta zewnętrznego. Należy zauważyć, że schemat operacji jest ścisłym widokiem schematu wewnętrznego i jako taki nie wprowadza zmian strukturalnych.

Opcjonalne definiowanie schematu operacji ma następujące zalety:

  • Deklarowanie użycia elementu w celu określenia, czy jest on częścią schematu żądania, schematu odpowiedzi, obydwu lub żadnej z tych wartości. 

  • Przypisywanie zewnętrznej nazwy elementu do elementu wewnętrznego. Przydatne, aby uniknąć klonowania usług wewnętrznych tylko w tym celu.

  • Lepsze zarządzanie odwołaniami do operacji GET i ich widoczność.

  • Obsługa struktur stylu HATEOAS poza schematem wewnętrznym. Pozwala to na bezproblemowe przetwarzanie wewnętrzne.

  • Dostarczanie tekstu pomocy dla poszczególnych elementów.

Poniższa dokumentacja zawiera pełną listę atrybutów dostępnych podczas tworzenia schematu operacji przychodzącej usługi internetowej.

Omawiane tematy

Definicja schematu operacji

Elementy specjalistyczne

Specyfikacja Open API

Definicja schematu operacji

Poniższe atrybuty definiują schemat operacji zewnętrznej, określający schemat żądania i odpowiedzi dla operacji.

Mnemonik Poprawne wartości Opis Przykłady
usage= "REQ"

Służy do wskazywania, że element powinien być uwzględniony tylko w schemacie żądania.

Jeśli wartość zostanie określona dla grupy lub elementu listy, będzie stosowana do całego kontenera. Określony element w kontenerze może nadpisać wartość domyślną kontenera.

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

Służy do wskazywania, że element powinien być uwzględniony tylko w schemacie odpowiedzi.

Jeśli wartość zostanie określona dla grupy lub elementu listy, będzie stosowana do całego kontenera. Określony element w kontenerze może nadpisać wartość domyślną kontenera.

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

Służy do wskazywania, że element powinien być uwzględniony w definicjach schematów żądania i odpowiedzi. Jest to opcja domyślna

Jeśli wartość zostanie określona dla grupy lub elementu listy, będzie stosowana do całego kontenera. Określony element w kontenerze może nadpisać wartość domyślną kontenera.

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

Służy do wskazywania, że element nie powinien być uwzględniony w definicjach schematu żądania ani odpowiedzi.

Jeśli wartość zostanie określona dla grupy lub elementu listy, będzie stosowana do całego kontenera. Określony element w kontenerze może nadpisać wartość domyślną kontenera.

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

Służy do mapowania elementu usługi internetowej na element wewnętrzny. Domyślnie przyjmuje się, że nazwa elementu wewnętrznego jest taka sama jak nazwa elementu usługi internetowej. Atrybut ten służy do przypisywania nazwy elementu zewnętrznego w schemacie operacji i mapowania jej na odpowiedni element wewnętrzny.

Należy pamiętać, że nie jest to wyrażenie XPath, lecz odwołanie do poprawnej nazwy elementu, która odpowiada strukturze rozszerzonego schematu wewnętrznego.

Właściciel elementu musi być taki sam jak właściciel schematu usługi internetowej. Jeśli podstawowy schemat operacji został rozszerzony (przy użyciu dynamicznego rozszerzenia obszaru danych), rozszerzający właściciel może odwoływać się tylko do swoich elementów w rozszerzeniu schematu usługi internetowej dla operacji.

Wewnętrzny element schematu:

<toDoPriority .../>

Element schematu operacji:

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

Służy do ustanawiania struktury grupy reprezentującej klucz obcy obiektu.

Sam element nie istnieje w schemacie wewnętrznym. Grupuje elementy wartości klucza obcego wraz z odpowiadającym im elementem _​link, który w czasie uruchomienia udostępnia adres URL punktu końcowego operacji GET tego obiektu. Konsumenci usługi internetowej mogą użyć łącza, aby uzyskać dane dla obiektu.

Wewnętrzny element schematu:

<user .../>

Grupa schematów operacji:

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

Służy do ustanawiania struktury grupy reprezentującej zbiór obiektów odpowiadający wewnętrznej liście usług.

Sam element nie istnieje w schemacie wewnętrznym. Grupuje listę wewnętrzną zmapowaną na element _​data wraz z odpowiednim elementem _​link, który w czasie uruchomienia udostępnia adres URL punktu końcowego operacji GET zbioru. Konsumenci usługi internetowej mogą skorzystać z łącza, aby uzyskać bardziej szczegółowy zestaw informacji dla każdego obiektu na liście.

Domyślnie wszystkie elementy z listy, do której występuje odwołanie, są uwzględniane w schemacie operacji. W razie potrzeby można jawnie odwoływać się do określonych elementów i definiować ich atrybuty.

Wewnętrzny element schematu:

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

Grupa schematów operacji:

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

"expression"

Składniki wyrażenia:

  • mo:’<maintenance object>’;

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

  • pk2:...;

  • pk3:...;

  • pk4:...;

  • pk5:...;

Parametry pk2-5 są wymagane do dopasowania definicji klucza głównego obiektu obsługi.

Dotyczy tylko elementów _self i _link. Atrybut jest używany do odwoływania się do domyślnej operacji GET dla obiektu zdefiniowanego przez jego obiekt obsługi lub obiekt biznesowy.

O operacji GET decyduje aplikacja w następujący sposób:

  • Jeśli obiekt biznesowy obiektu odwołuje się do operacji za pomocą opcji Operacja GET, zostanie ona użyta.

  • Jeśli obiekt obsługi obiektu odwołuje się do operacji za pomocą opcji Operacja GET, zostanie ona użyta.

  • Jeśli zostanie znaleziona operacja GET odwołująca się do obiektu obsługi, zostanie ona użyta.

Jeśli dla obiektu nie można określić operacji GET, jest zwracany standardowy tekst informujący, że łącze nie jest dostępne.
 
<_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

"expression"

Składniki wyrażenia:

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

Dotyczy tylko elementów _self i _link. Atrybut jest używany do odwoływania się do określonej operacji GET wraz z informacjami potrzebnymi do utworzenia jej parametrów ścieżki.

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

Elementy specjalistyczne

Definicja schematu operacji używa specjalistycznych nazw elementów zgodnych ze standardem Hypermedia as the Engine of Application State (HATEOAS). Elementy te powinny być definiowane tylko przez schemat operacji, ponieważ nie są one istotne dla wewnętrznej usługi operacji ani nie powinny być przez nią zarządzane.

Poniższa lista opisuje każdy element i sposób jego użycia.

Nazwa elementu Opis Przykłady
<_​self .../>

Dane właściwe odpowiedzi mogą uwzględniać element "_self", który zawiera adres URL punktu końcowego operacji GET powiązanej z obiektem zwróconym w odpowiedzi.

Jest to element opcjonalny. W schemacie operacji może występować tylko jeden taki element.

Więcej informacji zawiera sekcja dotycząca atrybutów definicji schematu getOperation=.

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

Dane właściwe odpowiedzi mogą zawierać klucze obce, a dla tych obiektów w odpowiedzi uwzględniony jest element "_link", który zawiera adres URL punktu końcowego operacji GET dla tego obiektu (jeśli istnieje).

Więcej informacji zawiera sekcja dotycząca atrybutu definicji schematu role= i getOperation=.

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

Udostępnia standardowe odwołanie do listy obiektów w schemacie wewnętrznym.

Więcej informacji zawiera sekcja dotycząca atrybutu definicji schematu role="COLL".

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

Atrybuty dokumentacji

Poniższe atrybuty stanowią dodatkową dokumentację dla poszczególnych elementów, zawartą w specyfikacji Open API usługi internetowej.

Mnemonik Poprawne wartości Opis Przykłady
helpText= "help text field name"

Służy do powiązania elementu z określonym rekordem tekstu pomocy zdefiniowanym dla przychodzącej usługi internetowej. Jeśli element jest zawarty zarówno w schemacie żądania, jak i w schemacie odpowiedzi, używany jest ten sam tekst pomocy.

Jeśli ten atrybut nie zostanie określony, a dla pola powiązanego z elementem wewnętrznym istnieje pojedynczy rekord pola tekstu pomocy, zostanie użyty ten rekord tekstu pomocy. Jeśli istnieje więcej niż jeden rekord pola tekstu pomocy, używany jest ten, w którym nazwa tekstu pomocy jest taka sama, jak nazwa pola.

Należy pamiętać, że element wewnętrzny jest powiązany z nazwą pola za pomocą atrybutów mdField= (jeśli istnieją), w przeciwnym razie za pomocą atrybutu mapField=.

Nie dotyczy to elementów _self i _link.

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

W tym przykładzie przychodząca usługa internetowa definiuje nazwę pola tekstowego pomocy "TD_​ENTRY", które zawiera tekst pomocy dla tego elementu. Ten sam tekst pomocy jest dołączany do elementu w schemacie żądania i odpowiedzi.
helpTextResponse= "help text field name"

Służy do powiązania elementu uwzględnionego zarówno w schemacie żądania, jak i w schemacie odpowiedzi z określonym rekordem tekstu pomocy, który ma być używany w kontekście schematu odpowiedzi.

Stosowane są te same reguły co w atrybucie helpText=.

 
<toDoEntryId usage="BOTH" helpText="TD_ENTRY" helpTextResponse="TD_ENTRY_RESP"/>
W tym przykładzie przychodząca usługa internetowa definiuje następujące rekordy tekstu pomocy:

  • Nazwa pola tekstu pomocy "TD_​ENTRY" opisuje element wysyłany w schemacie żądania.

  • Nazwa pola tekstu pomocy "TD_​ENTRY_​RESP" opisuje element wypełniony w schemacie odpowiedzi.