Todennus
Jokainen API-kutsu edellyttää todennustunnistetta pyynnön rungossa tai kyselyparametreissa. Kun olet kirjautunut sisään, löydät tunnisteesi napsauttamalla Panorama-selainlaajennusta. Nimeä tämä parametri pyynnössäsi nimellä authentication Token.
Siirto ja koodaus
Nykyinen API tukee vain JSON-tietomuotoa. On suositeltavaa määrittää application/json hyväksytyksi otsikoksi, mutta se ei ole pakollista.
API:n perusosoite
Panorama API:n perusosoite riippuu siitä, minkä vyöhykkeen alle oppilaitoksesi on rekisteröity. Jos et ole varma, missä vyöhykkeessä oppilaitoksesi on, ota yhteyttä asiakkuuspäällikköösi. Tietoturvaprotokollien vuoksi sallitaan vain https-yhteys.
Käyttäjä-, oppilaitos-, kurssi-, jakso- ja alitilimalleille:
Yhdysvaltain vyöhyke: https://panorama.yuja.com/api
Kanadan vyöhyke: https://panorama-cz.yuja.com/api
Euroopan vyöhyke: https://panorama-ez.yuja.com/api
Australian vyöhyke: https://panorama-az.yuja.com/api
Dokumenttimalleille:
Yhdysvaltain vyöhyke: https://panorama-api.yuja.com/
Kanadan vyöhyke: https://panorama-api-cz.yuja.com/
Euroopan vyöhyke: https://panorama-api-ez.yuja.com/
Australian vyöhyke: https://panorama-api-az.yuja.com/
REST API:n vastauskoodit
| Tilakoodi | Merkitys |
| 200 | OK |
| 201 | Luotu |
| 204 | Ei sisältöä |
| 400 | Virheellinen pyyntö |
| 401 | Ei valtuutusta |
| 403 | Kielletty |
| 404 | Ei löytynyt |
| 500 | Sisäinen palvelinvirhe |
| 502 | Virheellinen yhdyskäytävä |
Mallit
Panorama API on jaettu useisiin malleihin, joista kukin edustaa eri entiteettiä, kuten kursseja tai dokumentteja. Alla olevat mallit eivät välttämättä sisällä kaikkia käytettävissä olevia kenttiä, vaan näyttävät vain kyseisen mallin keskeiset kentät.
1 - Käyttäjämallin API:n yleiskatsaus
Käyttäjämalli edustaa kaikkia henkilöitä, jotka liittyvät annettuun käyttöoikeustunnisteeseen tai kuuluvat oppilaitokseen.
1.1 - Käyttäjämallien ydin
| Muuttuja | Tyyppi | Kuvaus |
| userId | string | Järjestelmän luoma yksilöllinen userId. |
| lmsUserId | string | LMS-järjestelmäsi käyttäjälle luoma userId. |
| string | Käyttäjän sähköpostiosoite. | |
| firstName | string | Käyttäjän etunimi. |
| lastName | string | Käyttäjän sukunimi. |
| role | string | Käyttäjän järjestelmärooli. |
| locked | boolean | Onko tämän käyttäjän järjestelmärooli lukittu vai ei. |
1.2 - Keskeiset päätepisteet
| Metodi | Polku | Kuvaus | Vaadittu käyttöoikeustaso |
| GET | /user/getUser | Hakee annettuun käyttöoikeustunnisteeseen liittyvän nykyisen käyttäjän. | Opiskelija |
| GET | /user/getPaginatedUsers | Hakee taulukon oppilaitoksesi käyttäjistä. | Ylläpitäjä |
| POST | /user/updateUserInfo | Päivittää käyttäjän etunimen, sukunimen ja sähköpostiosoitteen. | Ylläpitäjä |
1.2.1 - GET /user/getUser
Hakee annettuun käyttöoikeustunnisteeseen liittyvän nykyisen käyttäjän.
Esimerkkiosoite: https://panorama.yuja.com/api/user/getUser
Parametri:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
JSON-esimerkkitiedot:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tvc"}
1.2.2 - GET /user/getPaginatedUsers
Hakee taulukon oppilaitoksesi käyttäjistä.
Esimerkkiosoite: https://panorama.yuja.com/api/user/getPaginatedUsers
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
page |
integer |
Järjestelmän luoma yksilöllinen userId. |
pageSize |
integer |
Kullakin sivulla vastaanotettavien tietueiden määrä. |
JSON-esimerkkipyyntö:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc","page": 2,"pageSize": 10}
1.2.3 - POST /user/updateUserInfo
Päivittää käyttäjän etunimen, sukunimen ja sähköpostiosoitteen.
Esimerkkiosoite: https://panorama.yuja.com/api/user/updateUserInfo
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
userId |
string |
Päivitettävän käyttäjän yksilöllinen userId. |
firstName |
string |
Käyttäjän etunimi. |
| lastName | string | Käyttäjän sukunimi. |
| string | Käyttäjän sähköpostiosoite. |
JSON-esimerkkipyyntö:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc","userId": "2ffdc6e2-b250-4c53-b706-d4e2856beaeb","firstName": "Lauren","lastName": Barnes","email": "lauren.barnes@mail.utoronto.ca"}
2 - Alitilimallin API:n yleiskatsaus
Alitilimalli edustaa kaikkia alitilejä, jotka ovat API:a käyttävän henkilön käytettävissä.
2.1 - Alitilimallin ydin
Muuttuja |
Tyyppi |
Kuvaus |
|---|---|---|
subAccountId |
string |
Järjestelmän luoma yksilöllinen subAccountId. |
parentSubAccountId |
string |
Järjestelmän alitilin ylätason alitilille luoma yksilöllinen subAccountId. |
lmsSubAccountId |
string |
LMS-järjestelmäsi alitilille luoma subAccountId. |
lmsParentSubAccountId |
string |
LMS-järjestelmäsi alitilin ylätason alitilille luoma subAccountId. |
name |
string |
Alitilin nimi. |
2.2 - Keskeiset päätepisteet
Metodi |
Polku |
Kuvaus |
Vaadittu käyttöoikeustaso |
|---|---|---|---|
GET |
/subAccount/getPaginatedSubAccounts |
Hakee luettelon oppilaitoksesi alitileistä, joihin sinulla on käyttöoikeus. |
Aliylläpitäjä |
2.2.1 - GET /subAccount/getPaginatedSubAccounts
Hakee luettelon oppilaitoksesi alitileistä, joihin sinulla on käyttöoikeus.
Esimerkkiosoite: https://panorama.yuja.com/api/subAccount/getPaginatedSubAccounts
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
page |
integer |
Sivu, jolta aloitetaan (alkaa luvusta 1). |
pageSize |
integer |
Kullakin sivulla vastaanotettavien tietueiden määrä. |
JSON-esimerkkitiedot:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc","page": 2,"pageSize": 10}
3 - Jaksomallin API:n yleiskatsaus
Jaksomalli edustaa kaikkia jaksoja, jotka ovat API:a käyttävän henkilön käytettävissä.
3.1 - Jaksomallin ydin
Muuttuja |
Tyyppi |
Kuvaus |
|---|---|---|
termId |
string |
Järjestelmän luoma yksilöllinen termId. |
lmsTermId |
string |
LMS-järjestelmäsi jaksolle luoma termId. |
name |
string |
Alitilin nimi. |
start |
Date |
Jakson alkupäivämäärä. |
end |
Date |
Jakson loppupäivämäärä. |
3.2 - Lukukausimallin keskeiset päätepisteet
Metodi |
Polku |
Kuvaus |
Vaadittu käyttöoikeustaso |
|---|---|---|---|
GET |
/term/getPaginatedTerms |
Hakee organisaatiosi lukukausien taulukon. |
Opettaja |
3.2.1 - GET /term/getPaginatedTerms
Esimerkki-URL: https://panorama.yuja.com/api/term/getPaginatedTerms
Hakee organisaatiosi lukukausien taulukon.
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunnus. Käytetään pyynnön todentamiseen. |
page |
integer |
Sivu, jolta aloitetaan (alkaa luvusta 1). |
pageSize |
integer |
Kullakin sivulla vastaanotettavien tietueiden määrä. |
JSON-esimerkkitiedot:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc","page": 2,"pageSize": 10}
4 - Organisaatiomallin API:n yleiskatsaus
Organisaatiomalli hakee tietoja, joihin ylläpitäjillä ja alaylläpitäjillä on pääsy, kuten organisaatioraportit, sisältöraportit ja ongelmaraportit.
4.1 - Organisaatiomallin ydin
Muuttuja |
Tyyppi |
Kuvaus |
|---|---|---|
institutionId |
string |
Järjestelmän luoma yksilöllinen institutionId. |
lmsType |
string |
Organisaatioon liitetyn oppimisympäristön (LMS) tyyppi (esim. Canvas). |
name |
string |
Organisaation nimi. |
primaryIdentifierKey |
string |
Järjestelmän luoma yksilöllinen tunnisteavain. |
secondaryIdentifierKey |
string |
Järjestelmän luoma yksilöllinen toissijainen tunnisteavain. |
consumerKey |
string |
Järjestelmän luoma yksilöllinen avain, jota käytetään LTI 1.1:ssä. |
ltiSecret |
string |
Järjestelmän luoma yksilöllinen avain, jota käytetään LTI 1.1:ssä. |
clientId |
string |
Organisaatioon liitetty asiakastunnus (client Id). Käytetään LTI 1.3:ssa. |
deploymentId |
string |
LTI-käyttöönottoon liitetty käyttöönottotunnus (deployment Id). Käytetään LTI 1.3:ssa. |
iss |
string |
Organisaatioon liitetty myöntäjä (issuer). Käytetään LTI 1.3:ssa. |
OIDCEndpoint |
string |
Organisaation OIDC-päätepiste. Käytetään LTI 1.3:ssa. |
JWKSEndpoint |
string |
Organisaation JWKS-päätepiste. Käytetään LTI 1.3:ssa. |
domain |
string |
Organisaation verkkotunnus. |
lmsAPILink |
string |
Organisaatioon liitetty API-päätepiste. |
accessToken |
string |
Organisaation käyttöoikeustunnus. Käytetään organisaatioon kohdistuviin API-pyyntöihin. |
4.2 - Organisaatiomallin keskeiset päätepisteet
Metodi |
Polku |
Kuvaus |
Vaadittu käyttöoikeustaso |
|---|---|---|---|
GET |
/institution/getInstitutionInformation |
Hakee tilisi organisaatioon liittyvät tiedot. |
Ylläpitäjä |
GET |
/institution/exportInstitutionReport |
Lataa liitetyn organisaation saavutettavuusraportin. Sen voi rajata alatileihin ja lukukausiin, joihin sinulla on käyttöoikeus. |
Alaylläpitäjä |
GET |
/content/exportContentReportData |
Lataa liitetyn organisaation sisältöraportin. Sen voi rajata alatileihin ja lukukausiin, joihin sinulla on käyttöoikeus. |
Alaylläpitäjä |
GET |
/issue/exportIssuesReport |
Lataa liitetyn organisaation ongelmaraportin. Sen voi rajata alatileihin ja lukukausiin, joihin sinulla on käyttöoikeus. |
Alaylläpitäjä |
4.2.1 - GET /institution/getInstitutionInformation
Hakee tilisi organisaatioon liittyvät tiedot.
Esimerkki-URL: https://panorama.yuja.com/api/institution/getInstitutionInformation
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunnus. Käytetään pyynnön todentamiseen. |
JSON-esimerkkitiedot:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc"}
4.2.2 - GET /institution/exportInstitutionReport
Lähetä LMS-saavutettavuusraportti sähköpostiin ja lataa se. Raportin voi rajata alatileihin ja lukukausiin, jolloin voit tarkastella organisaatiosi ja kurssiesi kaikkia olennaisia tietoja.
Esimerkki-URL: https://panorama.yuja.com/api/institution/exportInstitutionReport
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunnus. Käytetään pyynnön todentamiseen. |
subAccountId |
string |
Alatilin tunnus, jonka mukaan haluat rajata raportin. Valinnainen. |
terms |
array |
Lukukauden tunnus ja nimi, joiden mukaan haluat rajata raportin. Valinnainen. |
string |
Sähköpostiosoite, johon raportti lähetetään. |
|
shouldEmail |
Boolean |
Raportti lähetetään käyttäjälle sähköpostitse, jos arvo on "true". |
fileType |
string |
Tiedostotyyppi, jona haluat raportin. Vaihtoehdot: "Excel" tai "JSON" |
startYear |
integer |
Vuosi, josta haluat aloittaa. |
startMonth |
integer |
Kuukausi, josta haluat aloittaa. (Kuukaudet lasketaan alkaen luvusta 1, jolloin tammikuu on 1 ja joulukuu on 12.) |
endYear |
integer |
Vuosi, johon haluat lopettaa. |
endMonth |
integer |
Kuukausi, johon haluat lopettaa. (Kuukaudet lasketaan alkaen luvusta 1, jolloin tammikuu on 1 ja joulukuu on 12.) |
JSON-esimerkkitiedot:
{"authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc","subAccountId": "21a6a8d8-a609-4d60-ab21-9eca9013bb65","terms":"[{\"termId\":\"055e8635-c857-4f13-8b0f-63de5cb66aa1\",\"name\":\"Fall Term\"}]","email": "mathew.tyler@yuja.com",
"shouldEmail": true,"fileType": "Excel","startYear": 2022,"startMonth": 4,"endYear": 2023,"endMonth": 5}
4.2.3 - GET /content/exportContentReportData
Lataa liitetyn organisaation sisältöraportin, jonka voi halutessaan rajata alatileihin ja lukukausiin, joihin sinulla on käyttöoikeus.
Esimerkki-URL: https://panorama.yuja.com/api/content/exportContentReportData
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunnus. Käytetään pyynnön todentamiseen. |
subAccountId |
string |
Alatilin tunnus, jonka mukaan haluat rajata raportin. Valinnainen. |
termId |
string |
Lukukauden tunnus, jonka mukaan haluat rajata raportin. Valinnainen. |
string |
Sähköpostiosoite, johon raportti lähetetään. |
|
shouldEmail |
Boolean |
Raportti lähetetään käyttäjälle sähköpostitse, jos arvo on "true". |
fileType |
string |
Tiedostotyyppi, jona haluat raportin. Vaihtoehdot: "Excel" tai "JSON" |
startYear |
integer |
Vuosi, josta haluat aloittaa. |
startMonth |
integer |
Kuukausi, josta haluat aloittaa. (Kuukaudet lasketaan alkaen luvusta 1, jolloin tammikuu on 1 ja joulukuu on 12.) |
endYear |
integer |
Vuosi, johon haluat lopettaa. |
endMonth |
integer |
Kuukausi, johon haluat lopettaa. (Kuukaudet lasketaan alkaen luvusta 1, jolloin tammikuu on 1 ja joulukuu on 12.) |
JSON-esimerkkitiedot:
{"authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc","subAccountId": "21a6a8d8-a609-4d60-ab21-9eca9013bb65","termId": "60450295d546b0b925a2a7c4","email": "mathew.tyler@yuja.com","shouldEmail": true,"fileType": "Excel","startYear": 2022,"startMonth": 4,"endYear": 2023,"endMonth": 5}
4.2.4 - GET /issue/exportIssuesReport
Lataa liitetyn oppilaitoksen ongelmaraportti. Sen voi suodattaa alitileillä ja jaksoilla, joihin sinulla on käyttöoikeus.
Esimerkki-URL: https://panorama.yuja.com/api/issue/exportIssuesReport
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
subAccountId |
string |
Alitilin tunnus, jolla haluat suodattaa raportin. Valinnainen. |
termId |
string |
Jakson tunnus, jolla haluat suodattaa raportin. Valinnainen. |
string |
Sähköpostiosoite, johon raportti lähetetään. |
|
fileType |
string |
Tiedostotyyppi, jona haluat raportin. Vaihtoehdot: "Excel" tai "JSON" |
startYear |
integer |
Vuosi, josta haluat aloittaa. |
startMonth |
integer |
Kuukausi, josta haluat aloittaa. (Kuukaudet lasketaan 1:stä alkaen: tammikuu on 1 ja joulukuu on 12.) |
endYear |
integer |
Vuosi, johon haluat lopettaa. |
endMonth |
integer |
Kuukausi, johon haluat lopettaa. (Kuukaudet lasketaan 1:stä alkaen: tammikuu on 1 ja joulukuu on 12.) |
JSON-esimerkkitiedot:
{"authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc","subAccountId": "21a6a8d8-a609-4d60-ab21-9eca9013bb65","termId": "60450295d546b0b925a2a7c4","email": "mathew.tyler@yuja.com","fileType": "Excel","startYear": 2022,"startMonth": 4,"endYear": 2023,"endMonth": 5}
5 - Kurssimallin API:n yleiskatsaus
Kurssimalli hakee kurssit ja kurssiraportit
5.1 - Kurssimallin ydin
Muuttuja |
Tyyppi |
Kuvaus |
|---|---|---|
contextId |
string |
LMS-järjestelmäsi kurssille luoma kurssitunnus. |
name |
string |
Kurssin nimi. |
5.2 - Kurssimallin pääpäätepisteet
Metodi |
Polku |
Kuvaus |
Vaadittu käyttöoikeustaso |
|---|---|---|---|
GET |
/course/getPaginatedCourses |
Hakee taulukon oppilaitoksesi kursseista, joihin sinulla on käyttöoikeus. |
Opettaja |
GET |
/document/getPaginatedCourseDocuments |
Hakee taulukon kurssin dokumenteista. |
Opettaja |
GET |
/course/exportCourseReport |
Lataa liitetyn kurssin kurssiraportin. |
Ylläpitäjä |
5.2.1 - GET /course/getPaginatedCourses
Hakee taulukon oppilaitoksesi kursseista, joihin sinulla on käyttöoikeus.
Esimerkki-URL: https://panorama.yuja.com/api/course/getPaginatedCourses
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
page |
integer |
Sivu, jolta aloitetaan (alkaa luvusta 1). |
pageSize |
integer |
Kullakin sivulla vastaanotettavien tietueiden määrä. |
JSON-esimerkkitiedot:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc","page": 2,"pageSize": 10}
5.2.2 - GET /document/getPaginatedCourseDocuments
Hakee taulukon kurssin dokumenteista.
Esimerkki-URL: https://panorama.yuja.com/api/document/getPaginatedCourseDocuments
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Todennustunnisteesi. Käytetään pyynnön todentamiseen. |
contextId |
string |
Sen kurssin tunnus, jonka dokumentit haluat hakea. |
page |
integer |
Sivu, jolta haluat aloittaa (alkaa luvusta 1). |
pageSize |
integer |
Lukumäärä |
startYear |
integer |
Vuosi, josta haluat aloittaa. |
startMonth |
integer |
Kuukausi, josta haluat aloittaa. (Kuukaudet lasketaan 1:stä alkaen: tammikuu on 1 ja joulukuu on 12.) |
endYear |
integer |
Vuosi, johon haluat lopettaa. |
endMonth |
integer |
Kuukausi, johon haluat lopettaa. (Kuukaudet lasketaan 1:stä alkaen: tammikuu on 1 ja joulukuu on 12.) |
JSON-esimerkkitiedot:
{"authenticationToken": "1129c18a-eb75-4a11-8ccc-566646f94tcc","contextId": "362","page": 10,"pageSize": 12"startYear": 2022,"startMonth": 4,"endYear": 2023,"endMonth": 5}
5.2.3 - GET /course/exportCourseReport
Lataa liitetyn kurssin kurssiraportti.
Esimerkki-URL: https://panorama.yuja.com/api/course/exportCourseReport
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
authenticationToken |
string |
Käyttäjän todennustunniste. Käytetään pyynnön todentamiseen. |
contextId |
string |
Sen kurssin contextId, jonka raportin haluat hakea. |
string |
Sähköpostiosoite, johon raportti lähetetään. |
|
fileType |
string |
Tiedostotyyppi, jona haluat raportin. Vaihtoehdot: "Excel" tai "JSON" |
startYear |
integer |
Vuosi, josta haluat aloittaa. |
startMonth |
integer |
Kuukausi, josta haluat aloittaa. (Kuukaudet lasketaan 1:stä alkaen: tammikuu on 1 ja joulukuu on 12.) |
endYear |
integer |
Vuosi, johon haluat lopettaa. |
endMonth |
integer |
Kuukausi, johon haluat lopettaa. (Kuukaudet lasketaan 1:stä alkaen: tammikuu on 1 ja joulukuu on 12.) |
JSON-esimerkkitiedot:
{"authenticationToken": "1126c18a-ec75-4a11-8ccc-566146f94tcc","contextId": "202""email": "mathew.tyler@yuja.com","fileType": "Excel","startYear": 2022,"startMonth": 4,"endYear": 2023,"endMonth": 5}
6 - Dokumenttimalli
Dokumenttimalli hakee tietoja, jotka ilmaisevat dokumenttien ja niiden vaihtoehtoisten muotojen tilan.
6.1 - Dokumenttimallin päätepisteet
Muuttuja |
Tyyppi |
Kuvaus |
|---|---|---|
accessibilityFormats |
Array<ConversionFormat> |
Luettelo dokumentin vaihtoehtoisista muodoista ja siitä, missä käsittelyvaiheessa ne ovat. |
errorInterceptingDocument |
boolean |
Totuusarvo, joka ilmaisee, onko dokumentin haussa LMS-järjestelmästä tapahtunut virhe. |
accessibilityReportInfo |
AccessibilityReportInfo |
Dokumentin saavutettavuusraporttiin liittyvät tiedot. Saatavilla vain riittävillä käyttöoikeuksilla. |
fileTypeNotSupported |
boolean |
Totuusarvo, joka ilmaisee, onko dokumentin tiedostotyyppi Panoramassa tuettu. |
uploadedByStudent |
boolean |
Totuusarvo, joka ilmaisee, onko opiskelija ladannut dokumentin palvelimeen. |
formatsHiddenFromStudents |
boolean |
Totuusarvo, joka ilmaisee, onko dokumentin vaihtoehtoiset muodot piilotettu opiskelijoilta. |
sourceDocumentUnavailable |
boolean |
Totuusarvo, joka ilmaisee, onko lähdetiedoston haussa tapahtunut virhe. |
documentExpired |
boolean |
Totuusarvo, joka ilmaisee, onko dokumentti vanhentunut. |
documentId |
string |
Järjestelmän luoma yksilöllinen institutionId. |
documentFormat |
string |
Dokumentin tiedostopääte. |
documentName |
string |
Dokumentin nimi. |
documentType |
String |
Dokumentin tyyppi. |
documentSource |
string |
Dokumentin lähde. |
6.2 - Dokumenttimallin keskeiset päätepisteet
Metodi |
Polku |
Kuvaus |
Vaadittu käyttöoikeustaso |
|---|---|---|---|
POST |
/api/documentDetails |
Hakee kaikki tiedot määritetystä dokumentista. |
Opettaja saa täyden pääsyn API:in ja opiskelija rajoitetun pääsyn. |
POST |
/api/generateFormat |
Luo määritetylle dokumentille vaihtoehtoisen muodon tai saavutettavuusraportin. |
Opettaja saa täyden pääsyn API:in ja opiskelija rajoitetun pääsyn. |
POST |
/api/downloadFormatUrl |
Hakee lataus-URL-osoitteen, jolla voi ladata määritetyn dokumentin vaihtoehtoisen muodon. |
Opettaja saa täyden pääsyn API:in ja opiskelija rajoitetun pääsyn. |
6.2.1 - POST /api/documentDetails
Hakee kaikki tiedot määritetystä dokumentista.
Esimerkki-URL: https://panorama-api.yuja.com/api/documentDetails
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
identifierKey |
string |
Oppilaitoksesi ensisijainen identifierKey. |
extensionToken |
string |
Todennustunnisteesi. Käytetään pyynnön todentamiseen. |
documentId |
string |
Dokumentin yksilöllinen tunnus, jonka voi hakea sivutetusta kurssin dokumenttien API:sta kohdassa 5.2.2. |
JSON-esimerkkidata:
{
"identifierKey": "3b7a63c37e8c860bbb05bb550c5c1f0e817c2aad73056efd87bc848545a7f1j4",
"extensionToken": "1127c11a-eb75-4a41-8ccc-566646f94blc",
"documentId": "fcb6e196-b807-480d-9030-c29413e5bc2f1"
}
6.2.2 - POST /api/generateFormat
Luo määritetylle dokumentille vaihtoehtoisen muodon tai saavutettavuusraportin.
Esimerkki-URL: https://panorama-api.yuja.com/api/generateFormat
Huomautus: identifierKey ja extensionToken on määritettävä kyselyparametreiksi (Query Params). identifierKey on määritettävä avaimeksi (Key) ja extensionToken arvoksi (Value).
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
identifierKey |
string |
Oppilaitoksesi ensisijainen identifierKey. |
extensionToken |
string |
Todennustunnisteesi. Käytetään pyynnön todentamiseen. |
documentId |
string |
Dokumentin yksilöllinen tunnus. |
type |
string |
Valitse, haluatko luoda dokumentin (”generate”) vai käsitellä sen uudelleen (”reprocess”). Sallitut arvot: generate: Luo vaihtoehtoisen muodon, jos se ei ole saatavilla. reprocess: Käsittelee vaihtoehtoisen muodon uudelleen, jos se on jo luotu. |
format |
string |
Vaihtoehtoinen muoto, jonka haluat luoda tai käsitellä uudelleen. Sallitut arvot: enhanced_html report source base immersive_html gradient_txt txt epub brf mp3 png math_latex math_txt math_mp3 ocr_pdf ocr_reconstructed_docx ocr_txt ocr_mp3 |
language |
string |
Kieli, jolla vaihtoehtoinen muoto luodaan.
Jos käännöstä ei tarvita, kenttä tulee lähettää arvolla: default
Jos käännös tarvitaan, aseta kentän arvoksi kielikoodi. esimerkkejä: Kanadanranskan kohdalla kentän arvon tulee olla: fr-ca
Kreikan kohdalla kentän arvon tulee olla: el |
documentType |
string |
Dokumentin lähde, jonka dokumentin tiedot palauttava API palauttaa kohdassa 6.2.1. |
documentSource |
string |
Dokumentin lähde, jonka dokumentin tiedot palauttava API palauttaa kohdassa 6.2.1. |
JSON-esimerkkidata:
{
"identifierKey": "3b7a63c37e8c860bbb05bb550c5c1f0e817c2aad73056efd87bc848545a7f1j4",
"extensionToken": "1127c11a-eb75-4a41-8ccc-566646f94blc",
"documentId": "fcb6e196-b807-480d-9030-c29413e5bc2f1",
"type": "generate",
"format": "pdf",
"language": "el",
"documentType": "discussion",
"documentSource": "lms"
}
6.2.3 - POST /api/downloadFormatUrl
Esimerkki-URL: https://panorama-api.yuja.com/api/downloadFormatUrl
Huomautus: Palautettu lataus-URL on käytettävissä vain yhden tunnin ajan, ja muoto on täytynyt luoda aiemmin. Sen tilan on oltava complete (valmis), kun sitä tarkastellaan dokumentin tiedoista.
Parametrit:
Nimi |
Tyyppi |
Kuvaus |
|---|---|---|
identifierKey |
string |
Oppilaitoksesi ensisijainen identifierKey. |
extensionToken |
string |
Todennustunnisteesi. Käytetään pyynnön todentamiseen. |
documentId |
string |
Dokumentin yksilöllinen tunnus |
format |
string |
Vaihtoehtoinen muoto, jonka haluat ladata. Sallitut arvot: enhanced_html report source base immersive_html gradient_txt txt epub brf mp3 png math_latex math_txt math_mp3 ocr_pdf ocr_reconstructed_docx ocr_txt ocr_mp3 |
language |
string |
Kieli, jolla vaihtoehtoinen muoto luodaan.
Jos käännöstä ei tarvita, kenttä tulee lähettää arvolla: default
Jos käännös tarvitaan, aseta kentän arvoksi kielikoodi. esimerkki: Kanadanranskan kohdalla kentän arvon tulee olla: fr-ca
Kreikan kohdalla kentän arvon tulee olla: el |
JSON-esimerkkidata:
{
"identifierKey": "3b7a63c37e8c860bbb05bb550c5c1f0e817c2aad73056efd87bc848545a7f1j4", "extensionToken": "1127c11a-eb75-4a41-8ccc-566646f94blc",
"documentId": "fcb6e196-b807-480d-9030-c29413e5bc2f1",
"format": "pdf",
"language": "el"
}
7 - Dokumentin lähettäminen DocHubiin
Käyttäjät voivat lähettää dokumentin DocHubiin ohjelmallisesti ilman YuJa Panorama -portaalia. Lähetetyt tiedostot tallentuvat kutsuvan käyttäjän DocHubin juurikansioon, ja ne asetetaan automaattisesti jonoon saavutettavien muotojen luomista varten.
7.1.1 - POST /getPresignedUploadUrl
Pyydä esiallekirjoitettu lähetys-URL-osoite.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| authenticationToken | string | Kyllä | Käyttäjän todennustunniste. |
| filename | string | Kyllä | Tiedoston perusnimi ilman tiedostotunnistetta. |
| format | string | Kyllä | Tiedostotunniste ilman pistettä (katso tuettujen luettelo). |
| fileSize | number | Kyllä | Tiedoston koko tavuina. Koon on oltava ≤ 1 GB. |
JSON-pyyntöesimerkki:
{
"authenticationToken": "<authenticationToken>",
"filename": "Course-Syllabus-Fall-2026",
"format": "pdf",
"fileSize": 2457600
}
JSON-vastausesimerkki:
{
"url": "https://<bucket>.s3.<region>.amazonaws.com/",
"fields": {
"key": "my-content/institutions/<institutionId>/documents/<documentId>/file.<format>",
"bucket": "<bucket>",
"X-Amz-Algorithm": "AWS4-HMAC-SHA256",
"X-Amz-Credential": "...",
"X-Amz-Date": "...",
"Policy": "<base64-policy>",
"X-Amz-Signature": "..."
},
"documentId": "<uuid>",
"fileKey": "my-content/institutions/<institutionId>/documents/<documentId>/file.<format>"
}
7.1.2 - Tiedoston lähettäminen S3:een
Lähetä tiedosto S3:een: Lähetä tiedosto POST-pyynnöllä kohdassa 7.1.1 palautettuun "url"-arvoon multipart/form-data -pyyntönä. Lomakkeen osien järjestyksellä on merkitystä; S3 vaatii, että tiedosto tulee viimeisenä.
Huomautukset:
- "url" ja "fields" ovat AWS:n esiallekirjoitetun POST-pyynnön tiedot. Ne on käytettävä täsmälleen sellaisina kuin ne palautetaan.
- Säilytä "documentId" ja "fileKey"; ne annetaan kohdan 7.1.3 "processFile"-kutsulle.
- Esiallekirjoitettu POST on voimassa yhden tunnin.
Onnistunut lähetys palauttaa HTTP 204 -vastauksen ja tyhjän sisällön.
7.1.3 - POST /api/myContent/processFile
Tämä POST-pyyntö käskee YuJa Panoramaa käsittelemään tiedoston.
| Kenttä | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| authenticationToken | string | Kyllä | Käyttäjän todennustunniste. |
| documentId | string | Kyllä | Kohdassa 7.1.1 palautettu documentId. |
| fileKey | string | Kyllä | Kohdassa 7.1.1 palautettu fileKey. |
JSON-pyyntöesimerkki:
{
"authenticationToken": "<authenticationToken>",
"documentId": "3f8c2a1e-7b4d-4e9a-9c61-2d5f8e0b7a34",
"fileKey": "my-content/institutions/<institutionId>/documents/3f8c2a1e-7b4d-4e9a-9c61-2d5f8e0b7a34/file.pdf"
}