IBM TRIRIGA Application Platform Verze Příručka pro integraci služeb OSLC

IBM TRIRIGA Application Platform Verze 3.4.1

Příručka pro integraci služeb OSLC

Poznámka Před použitím těchto informací a produktu, který podporují, si přečtěte informace v části “Upozornění” na stránce 31.

Toto vydání se vztahuje k verzi 3, vydání 4, úpravě 1, produktu IBM TRIRIGA Application Platform a ke všem následným vydáním a úpravám, pokud nebude v nových vydáních uvedeno jinak. © Copyright IBM Corporation 2014, 2014.

Obsah Kapitola 1. Integrace dat pomocí služeb OSLC . . . . . . . . . . . . . . . . 1 Kapitola 2. Integrace jako spotřebitel služeb OSLC. . . . . . . . . . . . . 3 Komponenty služeb OSLC . . . . . . . . . . 3 Terminologie OSLC . . . . . . . . . . . 3 Poskytovatelé služeb a zjišování poskytovatelů služeb 4 Obory názvů OSLC. . . . . . . . . . . . 5 Operace a prostředky produktu OSLC . . . . . . 5 Tvary prostředků . . . . . . . . . . . . 6 Dokumenty shape . . . . . . . . . . . 7 Značky ETag . . . . . . . . . . . . . 10 Identifikátory URI produktu IBM TRIRIGA pro OSLC 10

Kapitola 3. Práce s prostředky OSLC . . 13 Dotazování prostředků OSLC . . . . . . . . Dotaz pomocí metody GET nebo POST . . . . Parametry dotazů OSLC . . . . . . . . . Vytváření prostředků OSLC . . . . . . . . . Vytvoření záznamů, které jsou přidružení primárních záznamů. . . . . . . . . . . . . . Aktualizace prostředků služeb OSLC . . . . . .

© Copyright IBM Corp. 2014, 2014

. . . .

13 13 14 17

. 18 . 19

Metoda HTTP PUT . . . . . Metoda HTTP PATCH . . . . Aktualizace propojených prostředků Odstranění prostředků OSLC . . . Práce s přílohami a binárními daty . . Zpracování příloh produktu OSLC . Zpracování binárních dat OSLC. .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

19 20 22 22 23 23 24

Kapitola 4. Administrace prostředků OSLC . . . . . . . . . . . . . . . 27 Zabezpečení OSLC . . . . . Změny hesel . . . . . . Hesla, kterým vypršela platnost . Protokolování OSLC . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

27 27 28 28

Kapitola 5. Odstraňování problémů se službami OSLC . . . . . . . . . . . 29 Vysvětlení kódů HTTP od OSLC .

.

.

.

.

.

.

. 29

Upozornění . . . . . . . . . . . . . 31 Zásady ochrany osobních údajů . Ochranné známky . . . . .

. .

. .

. .

. .

. .

. .

. .

. 32 . 33

iii

iv

© Copyright IBM Corp. 2014

Kapitola 1. Integrace dat pomocí služeb OSLC Aplikace produktu a některé externí aplikace mohou odkazovat a sdílet data pomocí integrace Služby OSLC (Open Services for Lifecycle Collaboration) (OSLC). Služby OSLC usnadňují spolupráci a sdílení dat mezi nástroji. Dodržením pravidel a metod, které jsou definovány specifikacemi, mohou aplikace provádět operace vytvoření, vyžádání, aktualizace a odstranění na prostředcích jiné aplikace. Komunita OSLC je skupina vývojářů softwaru a organizací, které pracují na standardizaci sdílení dat mezi nástroji životního cyklu softwaru, jako jsou např. požadavky, defekty, testovací případy a historie změn. Verze 2.0 specifikace OSLC je podporována pro integraci OSLC aplikací. Specifikace a další prostředky OSLC jsou k dispozici na webu. Integrace OSLC je uskutečněna mezi aplikací spotřebitele a externí aplikací poskytovatele. Aplikace poskytovatele OSLC učiní svá data prostředku dostupná pro aplikaci spotřebitele skrze kontejnery, jež známé jako poskytovatelé služeb. S dostupnými daty prostředku může aplikace spotřebitele vytvořit odkazy mezi svými daty a daty prostředku aplikace poskytovatele. Můžete nakonfigurovat a umožnit jakékoli aplikaci ve vašem produktu, aby se chovala jako aplikace spotřebitele OSLC. Aplikace spotřebitele mohou najít identifikátory URI, které identifikují prostředky v aplikaci poskytovatele, a použít tyto identifikátory URI například k vyžádání výsledků dotazu. Poskytovatelé služeb jsou k dispozici pro produkt IBM® TRIRIGA na adrese http://yourserver/oslc/sp. Identifikátory URI použité v požadavcích OSLC musí mít kódování adres URL.


1

2


Kapitola 2. Integrace jako spotřebitel služeb OSLC Vaši aplikaci, která je spotřebitelem služeb OSLC, můžete nakonfigurovat, aby podporovala 2 typy interakcí: dotaz a vytvoření. Odkazy prostředků získá aplikace spotřebitele od aplikace poskytovatele. Následující obrázek ilustruje interakci mezi aplikacemi odběratele a poskytovatele. Jako odběratel služeb OSLC se může aplikace dotazovat na prostředky nebo vytvářet prostředky v aplikaci poskytovatele a uchovávat si odkazy na tyto prostředky. Pomocí těchto odkazů může aplikace spotřebitele vytvářet požadavky pro aplikaci poskytovatele, které se dotazují, aktualizují nebo odstraňují prostředky.

Aplikace spotřebitele služeb OSLC (například IBM TRIRIGA Anywhere)

Aplikace poskytovatele služeb OSLC (například IBM TRIRIGA) Továrna na vytváření Schopnost dotazu

Odkazy prostředků

Data prostředku Odkaz prostředku byl vrácen

Aplikace spotřebitele aktualizuje nebo odstraní prostředek pomocí odkazu na prostředek

Komponenty služeb OSLC Poskytovatelé služeb, prostředky a značky ETqag poskytují podrobnosti, které potřebujete, abyste mohli spotřebovat data produktu IBM TRIRIGA skrze OSLC.

Terminologie OSLC Definice jsou poskytovány pro výrazy produktu IBM TRIRIGA OSLC. Aplikace spotřebitele Aplikace, která využívá data v centrálním datovém skladu pro specifické obchodní potřeby. továrna na vytváření Identifikátor URI, který se používá k vytvoření nových prostředků pomocí metody HTTP POST. Aplikace poskytovatele V kontextu služeb OSLC je to aplikace, která učiní svá data prostředku dostupná aplikaci spotřebitele skrze kontejnery, jež se nazývají poskytovatelé služeb. IBM TRIRIGA je aplikace poskytovatele pro mobilní aplikace IBM TRIRIGA Anywhere. Záznam poskytovatele Záznam, který identifikuje aplikaci poskytovatele a obsahuje definice pro jednu nebo více interakcí služeb OSLC mezi aplikací spotřebitele a aplikací poskytovatele.


3

public URI (veřejný identifikátor URI) Kořenový identifikátor URI, který se používá pro přístup k aplikaci poskytovatele služby OSLC. query capability (schopnost dotazu) Základní identifikátor URI pro vytvoření identifikátorů URI prostředku. resource (prostředek) V kontextu služby OSLC je to objekt síových dat nebo služba, kterou je možné identifikovat identifikátorem URI. Resource Description Framework (RDF) Rámec pro reprezentaci informací na webu. Tvar prostředku Specifikace, která definuje neměnný seznam vlastností prostředku, očekávané typy dat a hodnoty a pravidla pro ověření platnosti pro nové nebo změněné prostředky. resource type (typ prostředku) V kontextu služby OSLC je to typ dat, na který je odkázáno mezi integrovanými aplikacemi, např. požadavek na změnu stavu pracovní úlohy. service provider (poskytovatel služeb) V kontextu služeb OSLC je to kontejner prostředků, který je hostován nástrojem nebo produktem, aby se povolilo používání prostředků. Tar dokumentu Záznam, který popisuje tvar prostředku a činí ho dostupným skrz identifikátor URI.

Poskytovatelé služeb a zjišování poskytovatelů služeb Poskytovatel služeb je kontejner nebo kolekce prostředků, kterou hostuje nástroj nebo produkt. Poskytovatelé služeb podporují seskupování podobných procesů, jako jsou např. defekty nebo úlohy, které lze nakonfigurovat pro integraci. Poskytovatel služeb v aplikaci poskytovatele služeb OSLC obsahuje data prostředků, jenž se mohou pomocí integrace aplikací odkazovat na data aplikace spotřebitele. Data prostředku v produktu IBM TRIRIGA mohou být ve vícebajtových jazycích. Chcete-li integrovat aplikaci spotřebitele a aplikací poskytovatele, spotřebitel musí zjistit nebo identifikovat poskytovatele služeb, kteří jsou k dispozici v aplikaci poskytovatele. V produktu IBM TRIRIGA může být poskytovatel služeb jednoduchý, nebo složitý jako aplikace, která obsahuje mnoho modulů a obchodních objektů. Poskytovatele služeb můžete v produktu IBM TRIRIGA zjistit pomocí jedné z následujících metod: v Z nabídky Nástroje > Nastavení systému > Integrace > Správce služeb OSLC v Použitím identifikátoru URI: http://váš_server/oslc/sp Každá metoda vrátí seznam poskytovatelů služeb. Následující příklad ukazuje identifikátor URI pro zaměstnance: http://váš_server/oslc/sp/Employee. Identifikátor URI ukazuje na dokument poskytovatele služeb, který je ve formátu RDF/XML. Formát RDF/XML podporují dokumenty tvaru, poskytovatelé služeb a data prostředku. Aplikace spotřebitele může použít formulář poskytovatele služeb k určení dostupných prostředků a jejich podporovaných služeb, jako je např. dotaz nebo vytvoření. Poskytovatel služeb OSLC podporuje továrnu na vytvoření OSLC a operace schopnosti dotazování, které uživatelům poskytují identifikátor URI k vytvoření nebo vyhledání

4


prostředků, jež podporuje poskytovatel služeb. Dokument poskytovatele služeb popisuje dostupné prostředky a mapování oboru názvů a operace, které poskytovatel služeb podporuje pro dané prostředky. V následující ukázkové odezvě se na poskytovatele služeb OSLC odkazuje z vlastnosti rdfs:member. Dokument poskytovatele služeb pro doménu ukazuje identifikátor URI pro pracovní úlohu:

Obory názvů OSLC Specifikace OSLC definují obecné obory názvů. Vlastnost prefixDefinition uvádí všechna mapování předpon na obory názvů, která poskytovatel služeb používá k popisu prostředků, které spravuje. Obor názvů vlastnosti musí končit znakem # nebo /. Například http://yourserver/ns/ property#. Následující tabulka uvádí ukázku oborů názvů poskytovatele OSLC: Předpona

Obor názvů

rdf

http://www.w3.org/1999/02/22-rdf-syntax-ns#

oslc

http://open-services.net/ns/core#

dcterms

http://purl.org/dc/terms/

asset

http://open-services.net/ns#

foaf

http://xmlns.com/foaf/0.1/

rdfs

http://www.w3.org/2000/01/rdf-schema#

rr

http://jazz.net/ns/ism/registry#

spi

http://jazz.net/ns/tririga

Následující výňatek ze sekce služeb v dokumentu poskytovatele služeb uvádí obory názvů OSLC a RDF: oslc rdf

Operace a prostředky produktu OSLC Poskytovatel služeb OSLC podporuje operace továrny na vytváření a schopností dotazů pro prostředky, které jsou k dispozici v dokumentu poskytovatele služeb. Továrna na vytváření poskytuje identifikátor URI vytvoření oslc:creation, který použijete k vytváření nových prostředků s pomocí metody HTTP POST. Identifikátor URI dotazu oslc:queryBase

Kapitola 2. Integrace jako spotřebitel služeb OSLC

5

použijete pro výběr kolekce prostředků spravované poskytovatelem služeb. Když je prostředek získán za použití dotazu nebo vytvoření, je možné jej aktualizovat nebo odstranit.

Operace továrny na vytváření Pokud prostředek podporuje vytváření, může existovat jedna operace továrny na vytváření. Následující výňatek z dokumentu poskytovatele služeb uvádí operaci továrny na vytváření, adresu URL tvaru prostředku a adresu URL operace vytvoření prostředku, která tvar vytvoří. Create WorkTask OSLC creation factory for WorkTask ......

Operace schopnosti dotazu Identifikátor URI dotazu je oslc:queryBase a následující příklad zobrazuje vyhledání pracovní úlohy s pomocí požadavku: : WorkTask OSLC query capability for WorkTask

Definujete-li tvar prostředku OSLC, všechny dotazy na daný prostředek budou k dispozici přes poskytovatele služeb. Dotazy se zpřístupní pomocí schopností dotazování produktu OSLC. Tvar prostředku OSLC je definován v sestavě definované ve správci sestav produktu IBM TRIRIGA. Tvar prostředku používá sestavu jako šablonu k definování vlastností dostupných pro daný prostředek. Tyto vlastnosti jsou pak vráceny, když spustíte schopnost dotazu. Každá schopnost dotazu obsahuje vlastnost nazývanou základ dotazu, kterou použijete, chcete-li pro daný prostředek použít rozšířená kritéria. Tato kritéria umožňují předdefinovat filtry pro stejný tvar. Pole Základ dotazu ve schopnosti dotazu uchovává název dotazu, který je kompatibilní s dotazem, na kterém je definován prostředek. Tento dotaz, pokud je definován, se používá pro filtrování. Parametry TRIRIGA můžete použít v dotazu, jako je $$USERID$$, $$RECORDID$$ nebo $$PARENT::SECTIONAME::FIELDNAME$$. Základ dotazu je seznam a obsah seznamu se změní, když se změní prostředek. Dotaz MyWorkTask například vrátí seznam pracovních úloh, které jsou přiřazeny k uživateli, který vytváří požadavek na dotaz.

Tvary prostředků Tvar prostředku je soubor RDF (Resource Description Framework), který obsahuje popis typů dat prostředku, jež můžete použít v interakci. Tvar obsahuje seznam atributů prostředku. Soubor RDF můžete zobrazit pro prostředek na kartě Náhled formuláře prostředku. Tvar prostředku se podobá schématu XML v tom smyslu, že definuje datovou strukturu prostředku.

6


Dokumenty shape Dokument shape v produktu OSLC je elektronický způsob zobrazení prostředku, včetně všech závislostí, atributů a vlastností. Například dokument shape pracovní úlohy vypisuje podrobnosti prostředků pracovní úlohy. Dokumenty shape pokrývají všechny prostředky, včetně aktiv, společností, nákupních objednávek a pracovních úloh. Dokument shape také uvádí, co je povinné. Dokument shape prostředku může zahrnovat odkazy na dokumenty shape podřízených objektů. Jako formát dokumentu shape se používá RDF/XML. Tvar prostředku uvádí vlastnosti, akce a propojené prostředky definované pro daný prostředek. Když v produktu IBM TRIRIGA vytvoříte nový prostředek s formulářem prostředku OSLC, musíte uvést modul, obchodní objekt a dotaz na obchodní objekt nebo musíte vybrat modul a dotaz na několik obchodních objektů. Začněte vytvořením dotazu v produktu IBM TRIRIGA. Když vytvoříte sloupce zobrazované v rámci dotazu, definujete počáteční vlastnosti. Pomocí akce Importovat všechna pole ve formuláři naimportujete sloupce zobrazení z dotazu jako vlastnosti prostředku. Proces importu se pokusí nastavit pole produktu IBM TRIRIGA na odpovídající hodnoty vlastností OSLC, jako například jen pro čtení. Po importu můžete pole upravit a můžete vlastnosti odebrat. Vlastnost dcterms:identifier vytvoří ID záznamu během procesu importu. Pole triRecordIdSY je povinné, pokud plánujete aktualizovat prostředek. Následující tabulka uvádí, jak se typy polí produktu IBM TRIRIGA mapují na typy hodnot vlastností OSLC: Typ pole produktu IBM TRIRIGA

Typ hodnoty vlastnosti OSLC

Logická hodnota

OslcPropertyValueType.Boolean

Obchodní objekt

OslcPropertyValueType.String

Klasifikace


Klasifikace se sbalenými řádky

OslcPropertyValueType.Decimal

Barva

OslcPropertyValueType.String Filtrujete-li pole barev, identifikátor URI musí být zakódován v adrese URL. Nahrate symbol # %23.

Kontrolní číslo


Datum


Datum a čas


Doba trvání


Finanční sestava se sbalenými řádky


Obraz


Pouze popisek


Seznam


Číslo


Heslo


Jen pro čtení systémem


Text


Čas



7

Typ pole produktu IBM TRIRIGA

Typ hodnoty vlastnosti OSLC

Měrná jednotka


Adresa URL


Propojený prostředek ukazuje na prostředek, který se má připojit. Poskytuje řetězce přidružení a popisuje vztah. Zde jsou příklady řetězců přidružení: Má aktivum, Spravuje a Přiřazeno k. Také můžete přidat propojený prostředek do vlastnosti. Propojený prostředek je povolen a volitelný pro pole lokátoru a sekce smart.

Příklad: Dokument shape pracovní úlohy Dokument shape pracovní úlohy uvádí všechny vlastnosti atributy a závislosti pracovní úlohy. Následující kód zobrazuje výňatek z dokumentu ve tvaru pracovní úlohy nazvaného WorkTask. V tomto dokumentu shape prostředku jsou zahrnuty čtyři vlastnosti, ale může zde být uvedeno mnohem více vlastností. false ID RecordInformation.triIdTX>/oslc:name> false TIMESTAMP Planned Start RecordInformation.triPlannedStartDT true Actual Total Cost RecordInformation.triActualTotalCostNU false Task Name RecordInformation.triNameTX WorkTask

8


Číselná pole: Atribut pro měřítko je poskytován pro číselná pole ve specifikaci OSLC. Měřítko je počet číslic napravo od desetinné čárky čísla. Pokud má číslo vlastní masku zobrazení, hodnota měřítka se vrátí na základě vlastní masky zobrazení. Pokud maska zobrazení chybí a není žádná nastavena měrná jednotka, je standardně vrácena hodnota dvě. Pokud je pro číselné pole nastavena měrná jednotka, ale neexistuje pro něj maska zobrazení, vrátí se měřítko masky zobrazení měrné jednotky. Znaky 0 a # jsou uvažovány v masce zobrazení, pokud je určeno měřítko. Příklad: Měřítko v číselných polích Následující příklad zobrazuje vrácené výsledky s hodnotou měřítka 3: <spi:scale> 3 false Cost triCostNU

Seznam a vlastnosti měrných jednotek: Můžete zobrazit hodnoty, které jsou povoleny pro seznam a vlastnosti měrných jednotek. Seznam nebo vlastnost měrných jednotek má prvek oslc:allowedValues s identifikátorem URI prostředku. Identifikátor URI vrací seznam dostupných hodnot, které lze použít pro tento seznam nebo vlastnost měrných jednotek. Příklad Následující příklad zobrazuje vlastnost v prvku oslc:allowedValues a poté seznam povolených hodnot, které vychází z identifikátoru URI v tomto prvku: Japonský jen false exampleUOM exampleUOM Americký dolar Kapitola 2. Integrace jako spotřebitel služeb OSLC

9

Švédská koruna/Kronor Brazilský real Ruský rubl Norská koruna Novozélandský dolar Britská libra Thajský baht Kanadský dolar Egyptská libra Euro Polský zlotý Jihokorejský won Maarský forint Jihoafrický rand Švýcarský frank Japonský jen Australský dolar Izraelský šekel Dánská koruna Indická rupie clIndiaRupee

Značky ETag Značka ETag (značka entity) je záhlaví HTTP používané k ověření, zda má klient (například mobilní zařízení) nejnovější verzi záznamu. Je-li vytvořen požadavek GET, v záhlaví odezvy se vrátí značka ETag. Značka ETag také umožňuje klientovi vytvářet podmíněné požadavky. Kromě podpory základních metod aktualizace HTTP PUT a HTTP PATCH podporuje OSLC také podmíněné aktualizace. Podmíněné aktualizace využívají značky entit HTTP a záhlaví If-Match k ověření, zda mají klienti aktuální entitu prostředku. Tento proces se používá pro zjištění chybných aktualizací a konfliktů časování. Například pokud si dva klienti načtou stejný prostředek, OSLC odešle s odezvou záhlaví ETag. Hodnota ETag je datum a čas poslední aktualizace prostředku. Klient uloží hodnotu záhlaví ETag a odešle ji jako součást záhlaví HTTP If-Match pro následný požadavek na aktualizaci. Server vyhodnotí záhlaví If-Match a určí, zda má klient starou verzi prostředku, nebo zda má nejnovější verzi prostředku. Pokud server určí, že verze klienta je stará, odešle zpět odezvu HTTP 412 Selhání předběžné podmínky. Klient načte prostředek znovu a odešle požadavek založený na aktualizované značce ETag. Pokud však server určí, že verze klienta je nejnovější verze, aktualizace bude implementována, pokud se nenajdou omezení databáze nebo obchodních ověření. Klient také může odeslat požadavek bez záhlaví If-Match, nebo s hodnotu záhlaví If-Match nastavenou na * (hvězdička). Odeslání tohoto požadavku je sémanticky stejné, jako když by se záhlaví If-Match v požadavku na aktualizaci nenacházelo. V obou případech bude aktualizace nepodmíněná. Pokud existuje prostředek odkazovaný identifikátorem URI a nenaleznou-li se žádné omezení databáze nebo obchodních ověření, aktualizace bude implementována.

Identifikátory URI produktu IBM TRIRIGA pro OSLC Identifikátory URI, které použijete pro připojení k produktu IBM TRIRIGA pomocí OSLC, jsou jedinečné. Pomocí následujících identifikátorů URI se připojíte k produktu IBM TRIRIGA:

10


Komponenta OSLC

Popis

Stránka systémových prostředků

http://yourserver/oslc

Přihlášení

http://yourserver/oslc/login

Odhlášení

http://yourserver/oslc/logout

Továrna na vytváření

http://yourserver/oslc/so

Schopnost dotazu

http://yourserver/oslc/spq

Podrobnosti dotazu

http://yourserver/oslc/so

Tvar prostředku

http://yourserver/oslc/shapes Chcete-li získat přístup ke stránce tvaru prostředku, použijte adresu http://yourserver/oslc/shapes/ ResourceShapeName

Poskytovatel služeb

http://yourserver/oslc/sp


11

12


Kapitola 3. Práce s prostředky OSLC K definování, jak mají uživatelé vytvářet, dotazovat se, aktualizovat nebo odstraňovat prostředky OSLC, použijte metody HTTP. U všech datových aktivit se použije zabezpečení produktu IBM TRIRIGA. Uživatel nemůže vytvořit, dotázat se, aktualizovat nebo odstranit záznam bez odpovídajícího zabezpečeného přístupu.

Dotazování prostředků OSLC Na prostředky OSLC se můžete dotazovat pomocí metody HTTP GET nebo HTTP POST. Chcete-li řídit způsob vyhledávání prostředků uživateli, změníte parametry dotazu. Specifikace OSLC definují pro dotazování prostředků odlehčenou syntaxi dotazů založenou na standardu SPARQL.

Dotaz pomocí metody GET nebo POST Dotazujete-li se na prostředky OSLC, můžete použít metodu HTTP GET nebo metodu HTTP POST. Dotazujete-li se na prostředky OSLC pomocí metody HTTP GET, parametry dotazu uvedete v identifikátoru URI. Je-li identifikátor URI delší než 2000 znaků, musíte se dotázat pomocí metody HTTP POST, namísto metody HTTP GET. Metodu HTTP POST můžete také použít, je-li identifikátor URI kratší než 2000 znaků, ale stále dlouhý, nebo chcete-li skrýt parametry dotazu, aby se v identifikátoru URI nezobrazily. Dotazujete-li se pomocí metody HTTP POST, nastavíte záhlaví HTTP Content-Type na application/x-www-form-urlencoded, odešlete identifikátor URI bez parametrů a uvedete parametry dotazu v těle požadavku HTTP.

Příklad: Dotaz pomocí metody HTTP GET Následuje příklad dotazu pomocí metody HTTP GET. Všechny parametry dotazu se zobrazí v identifikátoru URI. http://yourserver/oslc/spq/WorkTaskQuery?oslc.select= spi:triNameTX,spi:RCA{spi:triRCARemedyCL}&oslc.where= spi:RCA{spi:triRCARemedyCL="Clean"}&oslc.orderBy=%2Bspi:triNameTX

Příklad: Dotaz pomocí metody HTTP POST Následuje příklad stejného dotazu pomocí metody HTTP POST. Identifikátor URI bude kratší. http://yourserver1/oslc/spq/WorkTaskQuery

Tělo HTTP Text požadavku HTTP obsahuje všechny parametry dotazu. oslc.select=spi:triNameTX,spi:RCA{spi:triRCARemedyCL}&oslc.where= spi:RCA{spi:triRCARemedyCL="Clean"}&oslc.orderBy=%2Bspi:triNameTX


13

Parametry dotazů OSLC Parametry dotazů OSLC poskytují volby pro dotazování prostředků OSLC. Například parametr oslc.orderBy definuje pořadí výsledků dotazu. Podporované parametry dotazů HTTP OSLC jsou oslc.properties, oslc.where, oslc.orderBy, oslc.select, oslc.pageSize a pageno. Není-li vlastnost uvedena v sekci Obecné formuláře, musíte uvést název sekce pro tuto vlastnost, ve formátu sectionname#fieldname. Například triDetails#triTaskTypeCL.

Parametr oslc.properties Parametr dotazu oslc.properties uvádí seznam vlastností pro prostředek OSLC. Vlastnosti mohou pocházet ze samotného prostředku nebo z propojeného prostředku. Používá se k získání částečného znázornění prostředku. Parametr oslc.properties není použitelný pro prostředky kolekce. Prostředek kolekce je prostředek OSLC, který má za členy další prostředky OSLC.

Příklad: Vyžádání atributů Následující příklad požadavku uvádí, že hodnoty pro atributy shortTitle a isTask se vrátí ve výsledcích: http://yourserver/oslc/so/WorkTask/ 337?oslc.properties=oslc:shortTitle,spi:isTask

Příklad: Vyžádání atributů z propojených prostředků Následující požadavek uvádí, že se ve výsledcích vrátí hodnota názvu organizace zákazníka: http://yourserver/oslc/so/WorkTask/ 13353622?oslc.properties=*,spi:triCustomerOrgTX{spi:triNameTX}

Tento požadavek vytvoří následující výsledky: { spi:triNameTX: "WorkTask" spi:triStatusCL: "Draft" spi:triIdTX: "1027019" -spi:triCustomerOrgTX: { spi:triNameTX: "Company 01" rdf:about: "http://yourserver/oslc/so/OrganizationRS/12877121" } rdf:about: "http://yourserver/oslc/so/triWorkTaskRS/13353622" -trira:action: [10] 0: "triDelete" 1: "triInvalidUploadHidden" 2: "triIssue" 3: "triBaseline" 4: "triApplyTemplate" 5: "triCopy" 6: "triPlanHidden" 7: "triSave" 8: "triSaveAndClose" 9: "triTemporaryTemplate" -prefixes: { oslc: "http://open-services.net/ns/core#" rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#" trira: "http://jazz.net/ns/tririga#" dcterms: "http://purl.org/dc/terms/" } }

14


Parametr oslc.where Parametr oslc.where uvádí klauzuli WHERE, která se použije k filtrování sady výsledků dotazu. Můžete například chtít vidět seznam prostředků OSLC pracovní úlohy, které byly vytvořeny v nějakém časovém rozmezí a byly schváleny vedením. Můžete filtrovat podle propojených prostředků pomocí parametru oslc.where. Můžete například chtít filtrovat osoby podle jména správce, kterému se osoby hlásí. Klauzule WHERE služeb OSLC podporuje následující základní operátory porovnávání: Symbol

Popis

=

Rovnost v "value" = Equal to v "%value" = Ends with v "value%" = Starts with v "%value%" = Contains Nezapomeňte, že pokud jako součást vyhledávání ručně zapíšete identifikátor URI se symbolem %, musíte symbol kódovat takto: "%25hodnota"

!=

Nerovnost

<

Menší než

>

Větší než

<=

Menší nebo rovno

>=

Větší nebo rovno

Potřebujete-li filtrovat podle hodnoty null, zadáte za symbol slovo null.

Požadavky na parametr oslc.where Data jsou vyjádřena ve formátu ISO 8601. Pro typy polí Datum a Čas se zobrazí milisekundy, pokud pole obsahuje nenulovou hodnotu počtu milisekund. Specifikace OSLC podporuje v rámci logických výrazů logický operátor and. Logický operátor or není podporován. V následujícím příkladu je hodnota literálu pro stav uvedena v uvozovkách, protože vlastnost stavu má datový typ řetězec. Hodnota množství není v uvozovkách, protože je to desetinný datový typ. Celá čísla a logické hodnoty také nevyžadují uvozovky. Například spi:status="Closed" and spi:quantity>10.5 and spi:active=true, kde spi:active má datový typ logické hodnoty. Specifikace OSLC implicitně podporuje operátor or v jediné vlastnosti s uvedením operátoru in. Například chcete-li zobrazit všechny pracovní úlohy ve stavu Issued nebo Active, použijte dotaz spi:status in ["Issued","Active"]

Příklad: Vyhledání pracovních úloh, které byly vytvořeny v daném časovém rozsahu a jsou schválené Následující klauzule uvádí prostředky pracovních úloh, které byly vytvořeny v určitém časovém rozsahu: spi:status="Approved" and dcterms:created>"2003-07-07T09:50:00-04:00" and dcterms:created<="2004-07-07T09:50:00-04:00". Kapitola 3. Práce s prostředky OSLC

15

Pomocí parametru oslc.orderBy uvedete pořadí řazení Parametr oslc.orderBy definuje, jak jsou výsledky dotazu seřazeny. Například seznam pracovních úloh může být seřazen podle data nebo podle ID. Chcete-li uspořádat pracovní úlohy ve vzestupném pořadí podle data vytvoření a v sestupném pořadí podle odhadované doby trvání, použijte následující parametr oslc.orderBy: +dcterms:created,-spi:estimatedDuration. Znaménko + označuje vzestupné pořadí řazení a znaménko - označuje sestupné pořadí řazení. Hodnoty jsou odděleny čárkami. Následující parametr oslc.orderBy je neplatný, protože v syntaxi dotazu OSLC není uvedeno žádné výchozí pořadí řazení: dcterms:created,-spi:estimatedDuration. U názvu vlastností musí být explicitně uvedeno znaménko + nebo -. Parametr oslc.orderBy také podporuje vnořené vlastnosti, například dcterms:creator{+foaf:name}. Ve skutečné adrese URL znaménka + a - fungovat nebudou. V adrese URL musíte místo toho použít znaky %2B a %2D.

Příklad: Řazení založené na propojených prostředcích Pole propojených prostředků můžete využít jako kritérium řazení pro řazení nadřízených záznamů a propojených prostředků uvnitř nadřízených záznamů. Například mohou existovat dva hlavní objekty, které jsou nazvané M1 a M2. M1 má dva propojené prostředky nazvané L1 a L3 a M2 propojené prostředky L2 a L4. Pokud budete řadit hlavní objekty ve vzestupném pořadí, bez uvážení propojených prostředků, výsledky jsou M1, M2. Pokud budete řadit hlavní objekty v sestupném pořadí, výsledky jsou M2, M1. Protože však pro objekty existuje několik propojených prostředků, budete-li řadit ve vzestupném nebo sestupném pořadí, propojené prostředky se seřadí také. L1 a L3 se seřadí v rámci objektu M1, L2 a L4 se seřadí v rámci objektu M2.

parametr oslc.select Parametr oslc.select vyžaduje dílčí znázornění prostředků členů kolekce. Parametr oslc.select se vždy použije pro prostředek kolekce. Uvedete seznam vlastností, které se zahrnou do požadavku. Vybrané vlastnosti mohou pocházet ze samotného prostředku nebo z propojeného prostředku.

Příklad: Požadavek na dílčí prostředek Parametr oslc.select poskytuje seznam prověřených názvů vlastností oddělených čárkami. Parametr oslc.prefix není podporován. Následující požadavek je příklad dílčího požadavku na prostředek: oslc.select=oslc:shortTitle,dcterms:creator

Příklad: Vlastnosti z odkazovaných prostředků Pomocí parametru oslc.select můžete vybrat vlastnosti z odkazovaných prostředků. Chcete-li načíst informace, jako je například jméno tvůrce, uvedete příkaz SELECT: oslc.select= oslc:shortTitle,dcterms:creator{foaf:name}. Prostředek foaf:Person je jméno osoby uvedené v hodnotě vlastnosti tvůrce. Chcete-li získat z prostředku všechny vlastnosti, můžete použít parametr oslc.select=*. Stejnou syntaxi lze použít pro parametr oslc.properties, hledáte-li prostředek OSLC.

16


Příklad: Vlastnosti z propojených prostředků Pomocí parametru oslc.select vyberete vlastnosti z propojených prostředků. Chcete-li načíst informace, jako je například hodnota názvu organizace zákazníka, uvedete příkaz SELECT: http://yourserver/oslc/spq/WorkTaskQC ?oslc.select=*,spi:triCustomerOrgTX{spi:triNameTX} &oslc.where=spi:triCustomerOrgTX!="null"

Tento příkaz SELECT vrátí následující odezvu: { -rdf:members: [1] -0: { spi:triNameTX: "WorkTask" spi:triStatusCL: "Draft" spi:triIdTX: "1027019" -spi:triCustomerOrgTX: { spi:triNameTX: "Company 01" rdf:about: "http://yourserver/oslc/so/Organization/12877121" } rdf:about: "http://yourserver/oslc/so/WorkTask/13353622" -trira:action: [10] 0: "triDelete" 1: "triInvalidUploadHidden" 2: "triIssue" 3: "triBaseline" 4: "triApplyTemplate" 5: "triCopy" 6: "triPlanHidden" 7: "triSave" 8: "triSaveAndClose" 9: "triTemporaryTemplate" } rdf:about: "http://yourserver/oslc/spq/WorkTask" -prefixes: { oslc: "http://open-services.net/ns/core#" rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#" spi: "http://jazz.net/ns/tririga#" dcterms: "http://purl.org/dc/terms/" } }

Parametr oslc.pageSize Parametr oslc.pageSize uvádí počet výsledků, které server vrátí, na stránku. Například hodnota parametru oslc.pageSize=20 způsobí, že dotaz vrátí 20 výsledků na stránku.

parametr pageno Parametr pageno uvádí stránku, kterou server vrátí. Například hodnota parametru pageno=3 způsobí, že dotaz vrátí pouze data pro třetí stránku.

Vytváření prostředků OSLC Metodu HTTP POST použijte k vytvoření instance prostředku OSLC. Pak můžete prostředek sdílet s ostatními aplikacemi a aktualizovat jej pomocí metod PUT, PATCH a MERGE.

Informace o této úloze Klient OSLC odešle dokument JSON, který je podřízen tvaru prostředku, jak je publikován v dokumentu shape. Data se odešlou do OSLC v těle požadavku HTTP ve formátu JSON a záhlaví HTTP Content-Type je nastaveno na typ MIME application/json. Je-li požadavek Kapitola 3. Práce s prostředky OSLC

17

úspěšně zpracován, klient OSLC obdrží záhlaví HTTP umístění s identifikátorem URI nově vytvořeného prostředku. Chcete-li si prohlédnout vlastnosti nově vytvořeného prostředku, můžete zahrnout záhlaví vlastností do požadavku a označit tak, které vlastnosti chcete zobrazit. Vlastnost záhlaví s názvem Properties se vrátí s uvedenými vlastnostmi. Když odešlete požadavek na vytvoření, můžete zahrnout ID transakce do záhlaví požadavku HTTP. ID transakce musí být jedinečné napříč všemi aplikacemi klienta. OSLC uloží stav ID transakcí do databáze při dokončení požadavku. Pokud odešlete požadavek s ID transakce, OSLC zkontroluje, zda taková transakce existuje v databázi. Pokud transakce neexistuje, OSLC nespustí požadavek. Vrátí chybu, která označuje, že požadavek nebyl dokončen, protože ID transakce již existuje. Následuje ukázkové záhlaví s uvedeným ID transakce: Accept: application/rdf-xml transactionid: 6001 Content-Type: application/json;charset=utf-8

Je-li požadavek úspěšně zpracován, klient OSLC obdrží následující odpově: 201 Created Location: http://yourserver/oslc/so/WorkTask/10269 ETag: 1376596202470

Je-li akce předána, musí se jednat o platnou akci pro aktuální stav záznamu. Například je-li aktuální stav záznamu Koncept, platnou akcí bude často Uložit. Akce se zavolá po vytvoření záznamu. Pokud parametroslc.select na stránce s výsledky dotazu (oslc/spq) obsahuje zástupný znak (*), nebo pokud není uveden žádný parametr oslc.properties na stránce s podrobnostmi dotazu (oslc/os), výsledek bude zahrnovat všechny akce, které lze provést pro každý načtený záznam. Formát akce je "tririga:action":["action1","action2",...]. Požadavky OSLC mohou selhat z různých příčin, například z důvodu obchodního ověření, ověřování nebo autorizace. Například klient OSLC může obdržet chybu 400 Bad Request následovanou tělem HTTP s podrobnostmi o chybě.

Vytvoření záznamů, které jsou přidružení primárních záznamů Můžete pro primární záznamy vytvořit propojené závislé prostředky.

Informace o této úloze Můžete k primárnímu záznamu přidat přidružené závislé záznamy. Propojený prostředek určuje přidružení a přidružený prostředek.

Příklad: Vytvoření nákupní objednávky se dvěma položkami nákupní objednávky Následující metoda vytvoří prostředek nákupní objednávky se dvěma prostředky položky nákupní objednávky. Název propojeného prostředku je HasPOLineItem. { "spi:action":"Create Draft (triCreateDraft)", "spi:triNameTX":"oslcPO", "trirldr:HasPOLineItem": [ { "spi:action":"Create (triCreate)", "spi:triNameTX":"POLineItem1" }, { "spi:action":"Create (triCreate)",

18


"spi:triNameTX":"POLineItem2" } ] }

Je-li požadavek úspěšně zpracován, klient OSLC obdrží následující odpově: 201 Created Location: http://yourserver/oslc/so/PO/10269 ETag: 1376596202470

Aktualizace prostředků služeb OSLC Můžete použít metodu HTTP PUT k nahrazení prostředku služeb OSLC a metodu HTTP POST s atributem přepsání PATCH, abyste částečně aktualizovali prostředek služeb OSLC OSLC. Metoda HTTP PUT zcela nahradí data v prostředku za vlastnosti v požadavku. Metoda HTTP POST s křížovou metodou přepsání PATCH nahradí vlastnost lokálního prostředku za obsah v požadavku. Metoda HTTP POST s křížovou metodou přepsání PATCH a PATCHTYPE MERGE najde a dá do shody prvky lokálního prostředku z požadavku s prvky na serveru. V závislosti na tom, zda byla nalezena shoda, se prvky lokálního prostředku aktualizují, nebo vloží. Lokální prvek se nikdy neodstraní z vlastnosti lokálního prostředku. Když odešlete požadavek na aktualizaci, můžete zahrnout ID transakce do záhlaví požadavku HTTP. ID transakce musí být jedinečné napříč všemi aplikacemi klienta. OSLC uloží stav ID transakcí do databáze při dokončení požadavku. Pokud odešlete požadavek s ID transakce, OSLC zkontroluje, zda taková transakce existuje v databázi. Pokud transakce neexistuje, OSLC nespustí požadavek. Vrátí chybu, která označuje, že požadavek nebyl dokončen, protože ID transakce již existuje. Následuje ukázkové záhlaví s uvedeným ID transakce: Accept: application/rdf-xml transactionid: 6001 Content-Type: application/json;charset=utf-8

Metoda HTTP PUT Operace HTTP PUT se používá pro úplné nahrazení prostředku OSLC. Metoda PUT aktualizuje literálové vlastnosti i vlastnosti lokálních prostředků a odstraní vlastnosti lokálních prostředků, které nejsou zahrnuty v požadavku. Následující pravidla platí, použijete-li metodu PUT pro nahrazení prostředku OSLC: v Všechny literálové vlastnosti uvedené v dokumentu požadavku se aktualizují. Jakákoli literálová vlastnost, která není uvedena jako součást požadavku, není výslovně ovlivněna. Může na ni však mít implicitní dopad obchodní logika připojená k prostředku. Toto pravidlo je stejné, jako když k aktualizaci prostředku použijete metodu PATCH. v Všechny vlastnosti lokálního prostředku se nahradí odpovídajícími hodnotami z požadavku. Pokud v požadavku není zahrnuta vlastnost prostředku, odpovídající prostředek se odstraní. Je-li vlastnost prostředku zahrnuta, její hodnota nahradí hodnotu na serveru. v Odkazované prostředky nelze výslovně aktualizovat. Můžete však aktualizovat vlastnosti, které odkazují na prostředek, přičemž vlastnosti postupují podle modelu aktualizace literálových vlastností. Toto pravidlo je stejné, jako když k aktualizaci prostředku použijete metodu PATCH. V následujícím příkladu má prostředek pracovní úlohy jednu literálovou vlastnost, taskname, a jednu vlastnost prostředku parts. Vlastnost parts ukazuje na lokální Kapitola 3. Práce s prostředky OSLC

19

prostředek parts a je přidružena ke dvěma záznamům parts. Pokud požadavek PUT obsahuje vlastnost taskname a neobsahuje žádnou vlastnost parts, bude aktualizována vlastnost task a data vlastnosti parts budou odstraněna.

Příklad: Aktualizace literálové vlastnosti Následující metoda aktualizuje literálovou vlastnost taskname: PUT http://yourserver/oslc/so/WorkTask/123 { "dcterms:taskname": "Check-out Leaking – Modified for Test" }

Je-li požadavek úspěšně zpracován, klient OSLC obdrží následující odpově: 204 No Content ETag: 1376596202470

Parametr task se změní na Check-out Leaking – Modified for Test. Protože data vlastnosti parts nebyla v metodě zahrnuta, záznamy parts budou odstraněny.

Příklad: Aktualizace vlastnosti lokálního prostředku Následující metoda aktualizuje vlastnost prostředku parts: PUT http://yourserver/oslc/so/WorkTask/123 { “spi:parts”: [ { “spi:partsid": "0000000067", "spi:quantity": 5 } ] }

Je-li požadavek úspěšně zpracován, klient OSLC obdrží následující odpově: 204 No Content ETag: 1376596202470

Provede se vyhledání záznamu parts s ID 0000000067. Pokud daný záznam parts existuje, tak se aktualizuje. Pokud není nalezena žádná shoda, vytvoří se nový záznam parts. Všechna ostatní data vlastnosti parts pro tento prostředek pracovní úlohy se odstraní. Protože vlastnost taskname není v metodě zahrnuta, parametr task není součástí požadavku a hodnota nebude ovlivněna.

Metoda HTTP PATCH Metoda PATCH se používá pro částečnou aktualizaci prostředku OSLC. Metoda PATCH neodstraní žádné vlastnosti lokálního prostředku, které nejsou zahrnuty v požadavku. Požadavek PATCH odešle metoda POST se záhlavím x-method-override nastaveným na PATCH. Následující pravidla platí, použijete-li metodu PATCH pro nahrazení prostředku OSLC: v Všechny literálové vlastnosti uvedené v dokumentu požadavku se aktualizují. Jakákoli literálová vlastnost, která není uvedena jako součást požadavku, není výslovně ovlivněna. Může na ni však mít implicitní dopad obchodní logika připojená k prostředku. Toto pravidlo je stejné, jako když k nahrazení prostředku použijete metodu PUT. v Všechny vlastnosti lokálního prostředku se aktualizují nebo nahradí odpovídajícími hodnotami vlastností z požadavku. Pokud vlastnost prostředku není v požadavku zahrnuta,

20


odpovídající lokální prostředek není výslovně ovlivněn. Je-li vlastnost prostředku zahrnuta, její hodnota nahradí nebo aktualizuje hodnotu na serveru. Další vlastnosti prostředku se odstraní pomocí metody PATCH a nejsou odstraněny pomocí metody MERGE. v Odkazované prostředky nelze výslovně aktualizovat. Můžete však aktualizovat vlastnosti, které odkazují na prostředek, přičemž vlastnosti postupují podle modelu aktualizace literálových vlastností. Toto pravidlo je stejné, jako když k nahrazení prostředku použijete metodu PUT.

Příklad: Aktualizace literálové vlastnosti Následující metoda aktualizuje vlastnost task pracovní úlohy: POST http://yourserver/oslc/so/WorkTask/123 x-method-override: PATCH { "dcterms:taskname": "Check-out Leaking – Modified for Test" }

Na rozdíl od metody PUT, metoda PATCH neaktualizuje ostatní vlastnosti pracovní úlohy.

Příklad: Aktualizace vlastnosti lokálního prostředku Následující metoda aktualizuje určený záznam parts a odstraní ostatní data: POST http://yourserver/oslc/so/WorkTask/123 x-method-override: PATCH { "dcterms:taskname": "Check-out Leaking – Modified for Test", “spi:parts”: [ { “spi:partsid": "0000000067", "spi:quantity": 5 } ] }

Tato metoda se chová podobně jako metoda PUT. Systém vyhledá záznam parts s ID 0000000067. Pokud daný záznam parts existuje, tak se aktualizuje. Pokud není nalezena žádná shoda, vytvoří se nový záznam parts. Všechny ostatní záznamy parts pro tento prostředek pracovní úlohy se odstraní.

Příklad: Aktualizace a sloučení vlastnosti lokálního prostředku Následující metoda aktualizuje prostředek se záhlavím PATCHTYPE nastaveným na hodnotu MERGE: POST http://yourserver/oslc/so/WorkTask/123 x-method-override: PATCH PATCHTYPE: MERGE { "dcterms:taskname": "Check-out Leaking – Modified for Test", “spi:parts”: [ { “spi:partsid": "0000000067", "spi:quantity": 5 } ] }

Kapitola 3. Práce s prostředky OSLC

21

Provede se vyhledání záznamu parts s ID 0000000067. Pokud daný záznam parts existuje, tak se aktualizuje. Pokud není nalezena žádná shoda, vytvoří se nový záznam parts. Protože je záhlaví PATCHTYPE nastaveno na hodnotu MERGE, ostatní záznamy parts pro tento prostředek pracovní úlohy se ponechají beze změny.

Příklad: Vytvoření podmíněné aktualizace Následující metoda aktualizuje prostředek, pokud se hodnota značky ETag rovná 1376596202470: POST http://yourserver/oslc/so/WorkTask/123 x-method-override: PATCH if-match: 1376596202470

Je-li hodnota značky ETag 1376596202470, prostředek pracovního úlohy bude aktualizován a odešle se zpráva HTTP 204. Pokud není hodnota ETag 1376596202470, server odpoví zprávou HTTP 412. Tato zpráva znamená, že byl prostředek aktualizován jiným procesem a požadující klient má starou kopii prostředku. Klient musí provést metodu GET na prostředku 123, chce-li získat novou kopii prostředku. Následující tabulka shrnuje výsledek každé metody aktualizace, když se použije na různé typy prostředků. Metoda

Literálové vlastnosti

Lokální prostředky

Odkazované prostředky

PUT

Je-li vlastnost vynechána, tato vlastnost nebude ovlivněna.

Je-li vlastnost vynechána, tato vlastnost bude odstraněna.


PATCH




MERGE




Aktualizace propojených prostředků Odstranění prostředků OSLC Chcete-li odstranit prostředek OSLC, použijete metodu HTTP DELETE. Zadejte HTTP DELETE do identifikátoru URI prostředku. Platí-li pro obchodní objekt prostředku přechod stavu z aktuálního stavu prostředku do stavu null, stav objektu se změní na null. Neplatí-li pro obchodní objekt prostředku přechod stavu z aktuálního stavu prostředku do stavu null, stav objektu se nezmění. Můžete obchodní objekt upravit, aby zahrnoval přechod stavu z aktuálního stavu do stavu null. Nebo můžete aktualizovat záznam pomocí metody HTTP PUT nebo HTTP PATCH místo HTTP DELETE a předat název akce pro spuštění odstranění.

22


Má-li prostředek podřízené záznamy, tyto podřízené záznamy se odstraní, když je odstraněn prostředek. Má-li prostředek přidružené záznamy, při odstranění prostředku se odstraní přidružení, ale přidružené záznamy nebudou ovlivněny.

Práce s přílohami a binárními daty Klienti OSLC mohou načíst, vytvořit a aktualizovat přílohy a binární data pomocí rozhraní API OSLC.

Zpracování příloh produktu OSLC Zpracování příloh v produktu OSLC zahrnuje zpracování samotné přílohy, což je nestrukturovaný dokument, a zpracování přidružených metadat pro tento dokument. Metadata jsou popsána v souboru RDF prostředku AttachmentDescriptor. Prostředky AttachmentDescriptor jsou vždy přidruženy s přílohou ve vztahu 1:1.

Vytváření příloh OSLC Přílohy vytvoříte pomocí metody HTTP POST s binárním obsahem. Nepoužívejte požadavky HTTP POST s více částmi. Následující příklady ukazují požadavek HTTP na vytvoření přílohy, chcete-li zobrazit obraz přerušené části: POST http://yourserver/oslc/os/oslcwodetail/_abcd123/attachments Slug: brokenpart.jpeg Typ obsahu: image/jpeg Délka obsahu: 18124 x-document-description: A broken part x-document-meta: Attachment [binární obsah]

Následující příklad zobrazuje odezvu na požadavek: HTTP/1.1 201 CREATED Location: http://yourserver/oslc/os/oslcwodetail/_abcd123/attachments/1 Link: ; rel="describes" Content-Length: 0

Záhlaví Slug označuje název souboru. Pomocí záhlaví x-document-description můžete popsat přílohu. Tento popis je mapován do popisu dcterms:description prostředku deskriptoru přílohy. Pomocí záhlaví x-document-meta můžete označit název složky pro ukládání příloh.

Aktualizace příloh OSLC Přílohy OSLC můžete aktualizovat pomocí metody HTTP PUT s binárním obsahem. Nepoužívejte požadavky HTTP PUT s více částmi. Následující příklad zobrazuje požadavek HTTP na aktualizaci přílohy: PUT http://yourserver/oslc/os/oslcwodetail/_abcd123/attachments/1 Slug: brokenpart2.jpeg Typ obsahu: image/jpeg Délka obsahu: 18124 x-document-description: A broken part x-document-meta: Attachment [binární obsah]


23

Následující příklad zobrazuje odezvu na požadavek: HTTP/1.1 204 Content-Length: 0

Chcete-li aktualizovat pouze popis přílohy, můžete použít požadavek PATCH na identifikátor URI metadat, jak zobrazuje následující příklad: PATCH http://yourserver/oslc/os/oslcwodetail/_abcd123/attachments/meta/1 Content-Type: application/json { “dcterms:description”: “Broken pipe” }

Výběr příloh OSLC Přílohy jsou obvykle související prostředky strukturovaných prostředků, jako jsou pracovní příkazy nebo aktiva. Přílohy lze také přidružit k podřízeným prostředkům. Když je načten strukturovaný prostředek, standardně je poskytován jen odkaz na kolekci souvisejících příloh. Pokud spotřebitel očekává propojení podrobností příloh jako součást vlastněného strukturovaného prostředku, použijte následující formát dotazu: /oslc/os/oslcwodetail?oslc.select=res1,res2,spi:attachments{*}

Odstranění příloh OSLC Chcete-li odstranit přílohy OSLC, použijte následující požadavek: DELETE

Zpracování binárních dat OSLC Klienti OSLC mohou dotazovat a aktualizovat binární data pomocí rozhraní API OSLC. OSLC podporuje následující dva typy binárních dat: v Binární data produktu TRIRIGA se ukládají do tabulky dm_content. Každý prvek dat má jedinečné ID obsahu, název souboru a typ MIME pro vykreslení dat. Binární pole obsahuje ID obsahu. v Data obrázku jsou uložena jako soubory obrázku. Pole obrázku obsahuje částečnou cestu k souboru obrázku.

Dotazování binárních dat Když jsou binární data načtena pomocí dotazu OSLC nebo stránky podrobností o záznamu, hodnoty jsou uváděny s identifikátorem URI. Následující příklad uvádí identifikátor URI s informacemi o binárních datech: http://yourserver/oslc/so/supApp/168867/tririga:supBinary

Klient může použít identifikátor URI k načtení skutečných dat. V odpovědi HTTP identifikátoru URI text obsahuje obsah načtený z pole s obsahem tabulky dm_content. Záhlaví typu obsahu obsahuje typ binárních dat MIME. Stejně tak, když jsou data obrázku načtena pomocí dotazu OSLC nebo stránky podrobností o záznamu, hodnoty jsou uváděny s identifikátorem URI. Následující příklad zobrazuje identifikátor URI s informací o obrázku http://yourserver/oslc/so/supApp/168867/tririga:supImage

24


Klient může použít identifikátor URI k načtení skutečného obrázku. V odpovědi na HTTP identifikátoru URI text obsahuje obrázek, který je načten ze souboru obrázku. Záhlaví typu obsahu je typu MIME, který je složen z řetězce image/ plus přípona souboru obrázku.

Aktualizace binárních dat Pomocí samostatného požadavku HTTP aktualizujete každou binární vlastnost nebo vlastnost obrázku. Následující příklad zobrazuje formát požadavku na aktualizaci binárních dat nebo dat obrázku: http://localhost:8001/oslc/so/soID/property

V příkladu je soID ID inteligentního objektu, ke kterému patří binární vlastnost nebo vlastnost obrázku. Vlastnost identifikuje binární vlastnost nebo vlastnost obrázku, na kterou je hodnota nastavena. Používá běžnou formu předpony vlastnosti:NázevSekce-NázevVlastnosti, kde je část NázevSekce volitelné. Je použita metoda HTTP PUT a typ obsahu záhlaví HTTP obsahuje typ dat MIME takto: v Pro binární vlastnosti je typ MIMO předaný ve formě záhlaví typu obsahu předán přes typ dat MIME. Pomocí volitelného záhlaví Slug můžete předat název souboru. v Pro vlastnosti obrázku musí být typ obsahu obrázek. Typ je formát obrázku, jako je PNG nebo JPG. Název souboru je generován a typ obrázku je použit jako přípona souboru.


25

26


Kapitola 4. Administrace prostředků OSLC Podporu ověřování a autorizací pro služby OSLC poskytuje zabezpečení produktu IBM TRIRIGA. Protokolování OSLC použijete k ladění a vyhodnocování výkonu.

Zabezpečení OSLC Podporu ověřování a autorizací pro služby OSLC poskytuje zabezpečení produktu IBM TRIRIGA.

Nativní ověření Požadavek spotřebitele může poskytnout hodnoty uživatel:heslo, které jsou zakódovány ve formátu base64 a nacházejí se ve vlastnosti záhlaví OSLC.

Explicitní přihlášení a odhlášení Pokud aplikace spotřebitele potřebuje spustit příkazy pro explicitní přihlášení, použijete následující požadavek: GET http://yourserver/oslc/login?USERNAME=username&PASSWORD=password

Pokud aplikace spotřebitele potřebuje spustit příkazy pro explicitní odhlášení, použijete následující požadavek: GET http://yourserver/oslc/logout

Autorizace Řízení autorizace se poskytuje na úrovni obchodního objektu prostředku. Bezpečnostní zpracování dat prostředku je pak založeno na konfiguraci zabezpečení aplikace a skupině uživatelů, kam náleží uživatel, který požadavek vytvořil. Když se zpracovávají prostředky OSLC, jakýkoli atribut objektu, který je díky zabezpečení nakonfigurován jako skrytý, se nezahrne do odezvy na požadavek OSLC.

Změny hesel Aby mohl uživatel klienta změnit heslo, musíte vytvořit prostředek MůjProfil OSLC, který je založen na obchodním objektu Můj profil produktu IBM TRIRIGA. Chcete-li podporovat změny hesla, musíte vytvořit prostředek MůjProfil alespoň s definovanou vlastností Heslo. Můžete nadefinovat další vlastnosti pro podporu dalších změn profilu dle potřeby. Pomocí následujícího identifikátoru URI získáte přístup k prostředku MůjProfil v produktu OSLC: http://yourserver/oslc/so/MyProfile/userId

Tento identifikátor URI vždy vrátí aktuální profil uživatele, bez ohledu na to, jaké ID uživatele je zadané, protože uživatel nemá povoleno zobrazení profilů jiných uživatelů. Můžete nadefinovat schopnosti dotazu pro prostředek MůjProfil, ale výsledky dotazu nevrátí více než jeden profil aktuálního uživatele. Nemůžete nadefinovat továrny vytvoření prostředku MůjProfil.


27

Nemůžete v prostředku MůjProfil vytvořit nebo odstranit objekty MůjProfil pomocí produktu OSLC. Použijte metodu PATCH společně s identifikátorem URI, chcete-li změnit profil. Zahrňte následující řetězec formátu JSON do požadavku na změnu hesla: {..."spi:Password":"password",...}

Heslo je ve formě prostého textu a je šifrováno interně. Použijte metodu HTTP POST společně s následujícími záhlavími v požadavcích na změnu hesla: - x-method-override: PATCH - PATCHTYPE: CHPWD

ID prostředku, který představuje Můj profil, je nastaveno v souboru tririgaweb.properties takto: OSLC_MYPROFILE_RESOURCE=MyProfile

Hesla, kterým vypršela platnost Pokud heslu vypršela platnost, aplikace spotřebitele nemůže přistoupit k žádným prostředkům OSLC kromě identifikátoru URI změny hesla nebo odhlášení. Vrátí se chybová zpráva se stavem HTTP 403 Zakázáno. Pokud je definovaná systémová vlastnost OSLC_MYPROFILE_RESOURCE, vrácená chybová zpráva JSON zahrnuje identifikátor URI, který vede aplikaci zákazníka k identifikátoru požadavku na změnu hesla. Pravidla o vypršení platnosti hesla jsou nastavena v produktu TRIRIGA v umístění NástrojeNastavení systémuSystémNastavení hesla.

Příklad: Odezva na heslo, kterému vypršela platnost { oslc:Error: { spi:user: { rdf:resource: "http://yourserver/oslc/so/MyProfile/13417792" } oslc:message: "Heslu vypršela platnost" oslc:statusCode: 403 oslc:extendedError: "OSLC0054" } }

Protokolování OSLC Protokoly mohou zaznamenávat informace, které mohou být užitečné během ladění nebo vyhodnocování výkonu. Protokolování je spravováno na konzole administrátora produktu IBM TRIRIGA. Po přihlášení vyberte volby Protokolování platformy > OSLC. Chcete-li vypnout protokolování, vymažte zaškrtávací políčko OSLC. Další informace viz příručka IBM TRIRIGA Application Platform 3 Administrator Console User Guide.

28


Kapitola 5. Odstraňování problémů se službami OSLC Následující rady vám pomohou při odstraňování problémů, jste-li spotřebitelem služeb OSLC produktu IBM TRIRIGA. Tabulka 1. Rady pro odstraňování problémů se službami OSLC. Problém

Náprava

Tvar prostředku po přejmenování sestavy produktu IBM TRIRIGA již nefunguje

Pokud jste přejmenovali sestavu produktu IBM TRIRIGA, která je definována ve tvaru prostředku, tvar prostředku je narušen, protože definovaná sestava již neexistuje. Zobrazíte-li náhled schopnosti dotazu nebo použijete-li továrnu na vytváření, zobrazí se chybová zpráva. Obecný postup je aktualizovat tvar prostředku, když se změní název sestavy. Pokud se změní modul nebo obchodní objekt v sestavě produktu IBM TRIRIGA, hodnotu je potřeba také aktualizovat ve tvaru prostředku. Karta Kde se používá v sestavě označuje, který tvar prostředku danou sestavu používá.

Potřebujete protokoly pro ladění implementace OSLC

Protokolování je spravováno na konzole administrátora produktu IBM TRIRIGA. Po přihlášení vyberte volby Protokolování platformy > OSLC. Chcete-li vypnout protokolování, vymažte zaškrtávací políčko OSLC. Další informace viz příručka IBM TRIRIGA Application Platform 3 Administrator Console User Guide.

Došlo k trasování zásobníku olsc.where

Vložíte-li do parametru oslc.where jednoduché uvozovky, vytvoříte neplatnou adresu URL. Výjimka pochází z filtru Apache, který se vyskytne před tím, než parametr oslc.where dosáhne servletu OSLC. Není pod kontrolou produktu IBM TRIRIGA.

Vysvětlení kódů HTTP od OSLC OSLC používá standardní kódy odezvy HTTP jako chybové zprávy. Například odezva HTTP 404 se normálně vrací, když není nalezena webová stránka, a pro OSLC se kód odezvy 404 vrací, když nelze najít prostředek. Některé existující kódy chyb se standardně mapují na kódy HTTP, ale můžete namapovat další kódy dle potřeby. Pro OSLC jsou naimplementovány následující kódy odezvy HTTP: Kód HTTP

Vysvětlení od OSLC

200

Úspěch

201

Úspěch. Odezva obsahuje odkaz.

204

Prostředek byl úspěšně aktualizován. Neexistuje žádná entita odezvy.


29

Kód HTTP

Vysvětlení od OSLC

400

Chyba při obsloužení požadavku. Tato chyba může být způsobena obsahem požadavku nebo identifikátorem URI. Na straně serveru může například existovat chyba ověření obchodní logiky.

401

Selhání ověření.

403

Zakázáno. Platnost hesla uživatele vypršela.

404

Prostředek nelze nalézt nebo byl zadán neplatný typ prostředku.

405

Metodu HTTP nelze použít pro daný prostředek.

406

Požadované znázornění není podporováno.

410

Stránce stabilního prostředku vypršela platnost.

412

Prostředek na straně klienta je zastaralý a musí být obnoven ze serveru. Podmíněná aktualizace selhala, protože prostředek byl aktualizován jiným uživatelem nebo procesem.

500

Všechny ostatní chyby serveru.

Tyto zprávy podporují jazyky, které jsou podporovány produktem IBM TRIRIGA.

30


Upozornění Tyto informace jsou určeny pro produkty a služby nabízené ve Spojených státech. IBM nemusí produkty, služby nebo funkce popsané v tomto dokumentu nabízet v jiných zemích. Informace o produktech a službách, které jsou momentálně ve Vaší zemi dostupné, můžete získat od obchodního zástupce IBM pro Vaši oblast. Žádný z odkazů na produkty, programové vybavení nebo služby IBM neznamená, ani z něj nelze vyvozovat, že smí být použit pouze uvedený produkt, program nebo služba IBM. Použít lze jakýkoli funkčně ekvivalentní produkt, program či službu neporušující práva IBM k duševnímu vlastnictví. Za vyhodnocení a ověření operací libovolného produktu, programu či služby od jiného výrobce však odpovídá uživatel. IBM může mít patenty nebo podané žádosti o patent, které zahrnují předmět tohoto dokumentu. Vlastnictví tohoto dokumentu Vám nedává žádná práva k těmto patentům. Písemné dotazy ohledně licencí můžete zaslat na adresu: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. Pokud máte zájem o licenci v zemi s dvoubajtovou znakovou sadou (DBCS), kontaktujte IBM Intellectual Property Department ve Vaší zemi nebo zašlete písemné dotazy na adresu: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan Následující odstavec se netýká Velké Británie nebo kterékoliv jiné země, kde taková opatření odporují místním právním předpisům: SPOLEČNOST INTERNATIONAL BUSINESS MACHINES CORPORATION TUTO PUBLIKACI POSKYTUJE TAK, JAK JE (AS-IS), BEZ JAKÝCHKOLIV ZÁRUK, VYJÁDŘENÝCH VÝSLOVNĚ NEBO VYPLÝVAJÍCÍCH Z OKOLNOSTÍ, VČETNĚ, A TO ZEJMÉNA, ZÁRUK NEPORUŠENÍ PRÁV TŘETÍCH STRAN, PRODEJNOSTI NEBO VHODNOSTI PRO URČITÝ ÚČEL VYPLÝVAJÍCÍCH Z OKOLNOSTÍ. Právní řády některých zemí nepřipouštějí vyloučení záruk vyjádřených výslovně nebo vyplývajících z okolností v určitých transakcích, a proto se na vás výše uvedené omezení nemusí vztahovat. Tato publikace může obsahovat technické nepřesnosti nebo typografické chyby. Informace zde uvedené jsou pravidelně aktualizovány a v nových vydáních této publikace již budou tyto změny zahrnuty. IBM má právo kdykoliv bez upozornění zdokonalovat nebo měnit produkt(y) a program(y) popsané v této publikaci. Jakékoliv odkazy v této publikaci na webové stránky jiných společností jsou poskytovány pouze pro pohodlí uživatele a nemohou být žádným způsobem vykládány jako doporučení těchto webových stránek ze strany IBM. Materiály obsažené na takovýchto webových stránkách nejsou součástí materiálů k tomuto produktu IBM a tyto webové stránky mohou být používány pouze na vlastní nebezpečí.


31

IBM může, pokud to považuje za vhodné, používat nebo distribuovat libovolné informace, které jí poskytnete, aniž by tím vznikl jakýkoliv závazek IBM vůči Vám. Držitelé licence na tento program, kteří si přejí mít přístup i k informacím o programu za účelem (i) výměny informací mezi nezávisle vytvořenými programy a jinými programy (včetně tohoto) a (ii) vzájemného použití sdílených informací, mohou kontaktovat: IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 U.S.A. Informace tohoto typu mohou být dostupné za určitých podmínek. V některých případech připadá v úvahu zaplacení poplatku. IBM poskytuje licencovaný program popsaný v tomto dokumentu a veškeré dostupné licencované materiály na základě podmínek uvedených ve smlouvě IBM Customer Agreement, v Mezinárodní licenční smlouvě na programy IBM International Program License Agreement nebo v jiné ekvivalentní smlouvě. Informace týkající se produktů jiných společností byly získány od dodavatelů těchto produktů, z jejich tištěných materiálů nebo z jiných veřejně dostupných zdrojů. IBM tyto produkty netestovala a nemůže potvrdit jejich přesnost, kompatibilitu nebo jiná tvrzení, která se k těmto produktům vztahují. Otázky týkající se možností produktů jiných společností adresujte dodavatelům těchto produktů. Tyto informace obsahují příklady údajů a sestav používaných v každodenních obchodních operacích. Z důvodu zajištění co největší názornosti obsahují uvedené příklady jména osob, společností, názvy značek a produktů. Všechna tato jména jsou fiktivní a jakákoliv podobnost se jmény a adresami používanými skutečnými obchodními podniky je čistě náhodná. LICENČNÍ INFORMACE: Tyto informace obsahují ukázkové aplikační programy ve zdrojovém jazyce, které ilustrují programovací techniky na různých provozních platformách. Jste oprávněni kopírovat, upravovat a distribuovat tyto vzorové programy jakýmkoliv způsobem, aniž by vám tím vznikal jakýkoliv finanční závazek vůči IBM, pro účely vývoje, užívání, marketingu nebo distribuce aplikačních programů kompatibilních s rozhraním API pro operační systém, pro který byly vzorové programy napsány. Vzorové programy nebyly důkladně testovány za všech podmínek. IBM proto nezaručuje ani nenaznačuje spolehlivost, provozuschopnost nebo funkčnost těchto programů. Vzorové programy jsou poskytovány "JAK JSOU", bez záruky jakéhokoli druhu. IBM nenese odpovědnost za jakékoli škody vzniklé v důsledku vašeho užívání vzorových programů.

Zásady ochrany osobních údajů Softwarové produkty IBM, včetně řešení SaaS (software as a service solution) ("Nabídky softwaru"), mohou využívat soubory cookie nebo jiné technologie ke shromažování informací o užívání produktů s cílem zlepšit pracovní zkušenosti koncového uživatele, lépe přizpůsobit interakce s koncovým uživatelem nebo pro jiné účely. Nabídky softwaru shromažují v mnoha případech údaje, z nichž nelze určit totožnost. Některé z našich Nabídek softwaru vám mohou pomoci umožnit shromažování údajů, z nichž lze určit totožnost. Používá-li tato Nabídka softwaru soubory cookie ke sběru údajů, z nichž lze určit totožnost, naleznete níže specifické informace o užívání souborů cookie touto nabídkou.

32


Tato Nabídka softwaru nevyužívá soubory cookie nebo jiné technologie ke shromažování údajů, z nichž lze určit totožnost. Jestliže konfigurace implementované pro tuto Nabídku softwaru vám - jako zákazníkovi poskytují schopnost shromažovat od koncových uživatelů údaje, z nichž lze určit totožnost, prostřednictvím souborů cookie a jiných technologií, jste povinni vyhledat právní poradu ohledně právních předpisů, jež se vztahují na takový sběr dat, včetně veškerých požadavků týkajících se oznamování a vyžádání souhlasu. Informace o užívání různých technologií, včetně souborů cookie, pro tyto účely najdete v dokumentu IBM Privacy Policy na adrese http://www.ibm.com/privacy a v dokumentu IBM Online Privacy Statement na adrese http://www.ibm.com/privacy/details v části nazvané "Cookies, Web Beacons and Other Technologies" a v dokumentu "IBM Software Products and Software-as-a-Service Privacy Statement" na adrese http://www.ibm.com/software/info/ product-privacy/.

Ochranné známky IBM, logo IBM a ibm.com jsou ochranné známky nebo registrované ochranné známky společnosti International Business Machines Corp ve Spojených státech a případně v dalších jiných zemích. Ostatní názvy produktů a služeb mohou být ochrannými známkami IBM a ostatních společností. Aktuální seznam ochranných známek IBM je k dispozici na webu “Copyright and trademark information” na adrese www.ibm.com/legal/copytrade.shtml. Java™ a všechny ochranné známky a loga založené na termínu Java jsou ochranné známky společnosti Oracle a jejích příbuzných společností. Linux je ochrannou známkou společnosti Linus Torvalds ve Spojených Státech a případně v dalších jiných zemích. Microsoft, Windows, Windows NT, a logo Windows jsou ochranné známky společnosti Microsoft Corporation ve Spojených státech a případně v dalších jiných zemích. UNIX je registrovaná ochranná známka společnosti The Open Group ve Spojených státech a jiných zemích. Ostatní názvy produktů a služeb mohou být ochrannými známkami IBM a ostatních společností.

Upozornění

33

34


Vytištěno v Dánsku společností IBM Danmark A/S.

IBM TRIRIGA Application Platform Verze Příručka pro integraci služeb OSLC

Recommend Documents