Interfejs programistyczny aplikacji: Różnice pomiędzy wersjami
(→Tworzenie zadań i odbieranie raportów) |
|||
(Nie pokazano 14 wersji utworzonych przez 2 użytkowników) | |||
Linia 1: | Linia 1: | ||
− | Otwarty system antyplagiatowy udostępnia | + | Otwarty system antyplagiatowy udostępnia interfejs komunikacji do wersji lokalnej instalowanej na komputerze uczelni |
− | + | ||
− | + | ||
− | + | ||
+ | Interfejs zostały wykonany w oparciu o REST (Representational State Transfer). | ||
= API OSA = | = API OSA = | ||
+ | Aktualna wersja została opracowana na potrzeby integracji z systemem USOS. Docelowo chcemy ją rozszerzyć by można było się zintegrować z dowolnym oprogramowaniem. | ||
− | + | == API v1 == | |
+ | Wersja v1 została opracowana z myślą o USOS poniżej 6.1.2. Więcej na temat integracji z tym systemem tutaj: [[Konfiguracja APD]] | ||
− | == Tworzenie zadań i odbieranie raportów == | + | === Tworzenie zadań i odbieranie raportów === |
− | <pre>POST: http://<adres serwera osa>/api/job/create | + | <pre>POST: http://<adres serwera osa>/api/job/create (dla OSY ver. 3.4.4) |
+ | lub | ||
+ | POST: http://<adres_osy>/api/v1/usos/job (dla OSY ver. 3.5.0+ oraz ustawionym | ||
+ | parametrem -Dosa.usos-client.version=v1 w pliku setenv.sh) | ||
Uwaga! POST wysyłamy w kodowaniu UTF-8</pre> | Uwaga! POST wysyłamy w kodowaniu UTF-8</pre> | ||
Linia 21: | Linia 24: | ||
* <u>polonCode</u> - Kod POL-on uniwersytetu '''(w tej chwili OSA nie zapisuje tych informacji)''' | * <u>polonCode</u> - Kod POL-on uniwersytetu '''(w tej chwili OSA nie zapisuje tych informacji)''' | ||
* <u>languageCode</u> - Kod ISO języka pracy '''[możliwe pola: pl, en. Parametr tylko informacyjny - nie ma wpływu na wyniki]''' | * <u>languageCode</u> - Kod ISO języka pracy '''[możliwe pola: pl, en. Parametr tylko informacyjny - nie ma wpływu na wyniki]''' | ||
− | * documentType - Typ pracy '''[możliwe pola: licenciate, engineer, master, postgraduate, doctoral]''' | + | * documentType - Typ pracy '''[możliwe pola: licenciate, engineer, master, postgraduate, doctoral, habilitation]''' |
* <u>faculty</u> - Jednostka podstawowa | * <u>faculty</u> - Jednostka podstawowa | ||
* fieldOfStudy - Kierunek studiów '''(w tej chwili OSA nie zapisuje tych informacji)''' | * fieldOfStudy - Kierunek studiów '''(w tej chwili OSA nie zapisuje tych informacji)''' | ||
Linia 55: | Linia 58: | ||
Przykładowe dane przesłane przez API: | Przykładowe dane przesłane przez API: | ||
− | title='Motywowanie pracowników -narzędzia motywowania', author=' | + | title='Motywowanie pracowników -narzędzia motywowania', author='Jacecka, Mirosława', promoter='Kowalska, Ewa', |
− | reviewer=' | + | reviewer='Marcinkiewicz, Maciej', authorID='Jacecka, Mirosława, 1335132', promoterID='Kowalska, Ewa, 1344837', |
− | reviewerID=' | + | reviewerID='Marcinkiewicz, Maciej, 1335138', university='Uniwersytet DEMO', polonCode='UW', faculty='Wydział Zarządzania', |
documentType='licenciate', languageCode='pl', knowledgeArea='OB02', reportURL='https://apd.demo.usos.edu.pl/diplomas/osa/report/', file=XXXXX | documentType='licenciate', languageCode='pl', knowledgeArea='OB02', reportURL='https://apd.demo.usos.edu.pl/diplomas/osa/report/', file=XXXXX | ||
− | == | + | === Uwaga dla uczelni używających ExternalID dla wiązania prac z konkretnymi kontami w OSA === |
− | + | Pola '''promoterID''', '''authorID''', '''reviewerID''' - zostały wynegocjowane z USOSem. OSA wykorzystuje tylko promoterID w celu powiązania pracy z kontem Użytkownika OSA w taki sposób, że praca również wyświetla się danemu promotorowi w '''Moje dokumenty'''. W takim przypadku format wpisu powinien być jak powyżej, tj: | |
− | + | promoterID='Nazwisko, Imię, ExternalID' | |
− | = | + | oraz ExternalID musi się zgadzać z tym uzupełnionym w '''Użytkownicy -> Edytuj -> Zewnętrzne ID''' |
− | + | == API v2 == | |
+ | Wersja v2 została opracowana z myślą o USOS 6.1.2+. Więcej na temat integracji z tym systemem tutaj: [[Konfiguracja APD]] | ||
− | + | === Tworzenie zadań i odbieranie raportów === | |
− | = | + | <pre>POST: http://<adres_osy>/api/v2/usos/job (wymagana OSA ver. 3.5.0+) |
+ | - wymagany brak parametru na temat API w pliku setenv.sh lub ustawienie jego na -Dosa.usos-client.version=v2 | ||
+ | Uwaga! POST wysyłamy w kodowaniu UTF-8</pre> | ||
− | + | parametry (<u>podkreślone są wymagane</u>): (content-type: multipart/form-data;) | |
+ | * <u>action</u> - Rodzaj zgłoszenia | ||
+ | * <u>reportURL</u> - Adres do przesłania raportu (adres zwrotny) | ||
+ | * <u>metadata</u> - Metadane pracy w formacie JSON | ||
+ | * <u>file</u> - Plik pracy | ||
+ | * guid - Identyfikator zgłoszenia (wymagane przy action="update") | ||
− | + | odpowiedź: | |
+ | * status - Status zgłoszenia | ||
+ | * message - Tekstowy komunikat | ||
+ | * guid - Identyfikator zgłoszenia | ||
− | + | ---- | |
− | + | ||
− | + | Odnośnie '''action''': | |
+ | new - standardowe zgłoszenie | ||
+ | update - aktualizacja danych pracy o ID=guid i wysłanie ponownie aktualnego raportu PDF | ||
+ | ---- | ||
− | <pre> | + | Odnośnie '''metadata''' w formacie JSON: |
+ | <pre>{ | ||
+ | "university":"Politechnika Warszawska", | ||
+ | "polonCode":"PW", | ||
+ | "title":"O obrotach sfer niebieskich", | ||
+ | "languageCode":"pl", | ||
+ | "documentTypes":[ | ||
+ | "engineer", | ||
+ | "master" | ||
+ | ], | ||
+ | "faculties":[ | ||
+ | "Wydział Elektryczny", | ||
+ | "Wydział Fizyki" | ||
+ | ], | ||
+ | "fieldsOfStudy":[ | ||
+ | "Elekrotechnika", | ||
+ | "Fizyka chemiczna" | ||
+ | ], | ||
+ | "knowledgeAreas":[ | ||
+ | "OB01", | ||
+ | "OB05" | ||
+ | ], | ||
+ | "authors":[ | ||
+ | { | ||
+ | "firstName":"Mikołaj", | ||
+ | "lastName":"Kopernik", | ||
+ | "usosID":111223 | ||
+ | }, | ||
+ | { | ||
+ | "firstName":"Maria", | ||
+ | "lastName":"Skłodowska", | ||
+ | "usosID":111553 | ||
+ | } | ||
+ | ], | ||
+ | "promoters":[ | ||
+ | { | ||
+ | "firstName":"Michał", | ||
+ | "lastName":"Jachaś", | ||
+ | "usosID":441553 | ||
+ | }, | ||
+ | { | ||
+ | "firstName":"Sebastian", | ||
+ | "lastName":"Bąk", | ||
+ | "usosID":441123 | ||
+ | } | ||
+ | ], | ||
+ | "reviewers":[ | ||
+ | { | ||
+ | "firstName":"JJ", | ||
+ | "lastName":"Torpeda", | ||
+ | "usosID":422212 | ||
+ | }, | ||
+ | { | ||
+ | "firstName":"Domino", | ||
+ | "lastName":"Jachaś", | ||
+ | "usosID":453123 | ||
+ | } | ||
+ | ] | ||
+ | }</pre> | ||
+ | Jest to standard opracowany przez USOSa i dla OSY w niektórych miejscach jest nadmiarowy -> Uwagi do parametrów: | ||
+ | language - [pl, en, de, fr, it, ru, es, "" - jako inny] | ||
+ | polonCode - jest ignorowany | ||
+ | authors - OSA pobiera konkatenację wartości. USOS ID jest ignorowany | ||
+ | promoters - OSA pobiera konkatenację wartości. usosId=externalId pobierany jest pierwszej osoby | ||
+ | reviewers - OSA pobiera konkatenację wartości. USOS ID jest ignorowany | ||
+ | faculties - OSA pobiera konkatenację wartości | ||
+ | documentTypes - OSA pobiera pierwszą wartość. Parametry jak w v1 | ||
+ | knowledgeAreas - OSA pobiera pierwszą wartość. Parametry jak w v1 | ||
− | + | == FAQ == | |
− | + | === Po wysłaniu requestu metryka pracy nie posiada polskich liter === | |
− | + | * Wątek na [https://redmine.osaweb.pl/issues/632#change-2575 Redmine] poruszający ten problem dla integracji z systemem DSpace | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | == | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | == | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | = | + | = Zobacz też = |
+ | * [[API APD]] | ||
+ | * [[Konfiguracja APD]] | ||
+ | * [[Spis parametrów konfiguracyjnych]] | ||
+ | * [[Uzyskanie dostępu do Bazy Centralnej]] | ||
− | |||
− | [[Category:tech]] | + | <!--[[Category:tech]]--> |
Aktualna wersja na dzień 19:12, 28 lis 2019
Otwarty system antyplagiatowy udostępnia interfejs komunikacji do wersji lokalnej instalowanej na komputerze uczelni
Interfejs zostały wykonany w oparciu o REST (Representational State Transfer).
Spis treści
API OSA
Aktualna wersja została opracowana na potrzeby integracji z systemem USOS. Docelowo chcemy ją rozszerzyć by można było się zintegrować z dowolnym oprogramowaniem.
API v1
Wersja v1 została opracowana z myślą o USOS poniżej 6.1.2. Więcej na temat integracji z tym systemem tutaj: Konfiguracja APD
Tworzenie zadań i odbieranie raportów
POST: http://<adres serwera osa>/api/job/create (dla OSY ver. 3.4.4) lub POST: http://<adres_osy>/api/v1/usos/job (dla OSY ver. 3.5.0+ oraz ustawionym parametrem -Dosa.usos-client.version=v1 w pliku setenv.sh) Uwaga! POST wysyłamy w kodowaniu UTF-8
parametry (podkreślone są wymagane):
- reportURL - Adres do przesłania raportu (adres zwrotny)
- university - Nazwa uniwersytetu
- polonCode - Kod POL-on uniwersytetu (w tej chwili OSA nie zapisuje tych informacji)
- languageCode - Kod ISO języka pracy [możliwe pola: pl, en. Parametr tylko informacyjny - nie ma wpływu na wyniki]
- documentType - Typ pracy [możliwe pola: licenciate, engineer, master, postgraduate, doctoral, habilitation]
- faculty - Jednostka podstawowa
- fieldOfStudy - Kierunek studiów (w tej chwili OSA nie zapisuje tych informacji)
- knowledgeArea - Obszar wiedzy
- title - Tytuł pracy
- author - Autor
- promoter - Promotor
- reviewer - Recenzent
- file - Plik
odpowiedź:
- status - Status zgłoszenia
- message - Tekstowy komunikat
- guid - Identyfikator zgłoszenia
Po wykonanej analizie antyplagiatowej system próbuje odesłać raport na wskazany adres (reportURL) przekazując następujące parametry:
- id - Identyfikator zgłoszenia (GUID)
- file - Plik z raportem
oczekując następujących parametrów:
- status - Status
- message - Komunikat
Mapowanie kodów obszarów:
- OB01 -> Obszar nauk humanistycznych
- OB02 -> Obszar nauk społecznych
- OB03 -> Obszar nauk ścisłych
- OB04 -> Obszar nauk przyrodniczych
- OB05 -> Obszar nauk technicznych
- OB06 -> Obszar nauk rolniczych, leśnych i weterynaryjnych
- OB07 -> Obszar nauk medycznych i nauk o zdrowiu oraz nauk o kulturze fizycznej
- OB08 -> Obszar sztuki
Przykładowe dane przesłane przez API:
title='Motywowanie pracowników -narzędzia motywowania', author='Jacecka, Mirosława', promoter='Kowalska, Ewa', reviewer='Marcinkiewicz, Maciej', authorID='Jacecka, Mirosława, 1335132', promoterID='Kowalska, Ewa, 1344837', reviewerID='Marcinkiewicz, Maciej, 1335138', university='Uniwersytet DEMO', polonCode='UW', faculty='Wydział Zarządzania', documentType='licenciate', languageCode='pl', knowledgeArea='OB02', reportURL='https://apd.demo.usos.edu.pl/diplomas/osa/report/', file=XXXXX
Uwaga dla uczelni używających ExternalID dla wiązania prac z konkretnymi kontami w OSA
Pola promoterID, authorID, reviewerID - zostały wynegocjowane z USOSem. OSA wykorzystuje tylko promoterID w celu powiązania pracy z kontem Użytkownika OSA w taki sposób, że praca również wyświetla się danemu promotorowi w Moje dokumenty. W takim przypadku format wpisu powinien być jak powyżej, tj:
promoterID='Nazwisko, Imię, ExternalID'
oraz ExternalID musi się zgadzać z tym uzupełnionym w Użytkownicy -> Edytuj -> Zewnętrzne ID
API v2
Wersja v2 została opracowana z myślą o USOS 6.1.2+. Więcej na temat integracji z tym systemem tutaj: Konfiguracja APD
Tworzenie zadań i odbieranie raportów
POST: http://<adres_osy>/api/v2/usos/job (wymagana OSA ver. 3.5.0+) - wymagany brak parametru na temat API w pliku setenv.sh lub ustawienie jego na -Dosa.usos-client.version=v2 Uwaga! POST wysyłamy w kodowaniu UTF-8
parametry (podkreślone są wymagane): (content-type: multipart/form-data;)
- action - Rodzaj zgłoszenia
- reportURL - Adres do przesłania raportu (adres zwrotny)
- metadata - Metadane pracy w formacie JSON
- file - Plik pracy
- guid - Identyfikator zgłoszenia (wymagane przy action="update")
odpowiedź:
- status - Status zgłoszenia
- message - Tekstowy komunikat
- guid - Identyfikator zgłoszenia
Odnośnie action:
new - standardowe zgłoszenie update - aktualizacja danych pracy o ID=guid i wysłanie ponownie aktualnego raportu PDF
Odnośnie metadata w formacie JSON:
{ "university":"Politechnika Warszawska", "polonCode":"PW", "title":"O obrotach sfer niebieskich", "languageCode":"pl", "documentTypes":[ "engineer", "master" ], "faculties":[ "Wydział Elektryczny", "Wydział Fizyki" ], "fieldsOfStudy":[ "Elekrotechnika", "Fizyka chemiczna" ], "knowledgeAreas":[ "OB01", "OB05" ], "authors":[ { "firstName":"Mikołaj", "lastName":"Kopernik", "usosID":111223 }, { "firstName":"Maria", "lastName":"Skłodowska", "usosID":111553 } ], "promoters":[ { "firstName":"Michał", "lastName":"Jachaś", "usosID":441553 }, { "firstName":"Sebastian", "lastName":"Bąk", "usosID":441123 } ], "reviewers":[ { "firstName":"JJ", "lastName":"Torpeda", "usosID":422212 }, { "firstName":"Domino", "lastName":"Jachaś", "usosID":453123 } ] }
Jest to standard opracowany przez USOSa i dla OSY w niektórych miejscach jest nadmiarowy -> Uwagi do parametrów:
language - [pl, en, de, fr, it, ru, es, "" - jako inny] polonCode - jest ignorowany authors - OSA pobiera konkatenację wartości. USOS ID jest ignorowany promoters - OSA pobiera konkatenację wartości. usosId=externalId pobierany jest pierwszej osoby reviewers - OSA pobiera konkatenację wartości. USOS ID jest ignorowany faculties - OSA pobiera konkatenację wartości documentTypes - OSA pobiera pierwszą wartość. Parametry jak w v1 knowledgeAreas - OSA pobiera pierwszą wartość. Parametry jak w v1
FAQ
Po wysłaniu requestu metryka pracy nie posiada polskich liter
- Wątek na Redmine poruszający ten problem dla integracji z systemem DSpace
Zobacz też