Raportoinnin API-päätepisteet
Raportoinnin API:in sisältyvät päätepisteet ovat yksityisiä päätepisteitä, eikä niillä ole tällä hetkellä vanhentumiskäytäntöä. Anthology Ally voi muuttaa tai päivittää näitä päätepisteitä riippuen etenemissuunnitelmastamme tai tulevista julkaisuista.
Seuraavassa teknisessä dokumentaatiossa kerrotaan, miten päätepisteet määritetään ja mukautetaan oikein. Saat lisäohjeita tutustumalla artikkeliin, jossa kerrotaan Allyn API:n integroinnista ulkoiseen raportointityökaluun.
Käytettävissä olevat metodit
Allyn raportoinnin API:ssa on käytettävissä kaksi metodia. Ne kuvataan seuraavassa osiossa:
| Metodi | URL-osoite | HTTP-pyynnön tyyppi | Kuvaus |
| Overall | https://[alue]/api/v2/clients/[Ally-asiakastunnus]/reports/overall | GET | Oletusarvoisesti tämä menetelmä palauttaa tietojoukon, joka sisältää tietoja kurssista, sisältöeditorista (WYSIWYG) ja tiedostojen pistemääristä sekä kuhunkin kurssiin sisältyvistä LMS-esiintymästä peräisin olevista tiedostotyypeistä riippumatta siitä, onko Ally käytössä. |
| Issues | https://[alue]/api/v2/clients/[Ally-asiakastunnus]/reports/issues | GET | Oletusarvoisesti tämä menetelmä palauttaa tietojoukon, joka sisältää tiedot kaikista kullakin LMS-esiintymään sisältyvällä kurssilla esiintyvistä helppokäyttöisyysongelmista riippumatta siitä, onko Ally käytössä. |
Korvaa [Ally-asiakastunnus] omalla Ally-tuunnuksellasi. Jos et tiedä tunnustasi, voit pyytää sen luomalla tukipyynnön.
Korvaa [Alue] sen mukaan, millä alueella oppilaitoksesi Ally-ympäristöä isännöidään:
- Yhdysvaltain palvelinkeskus: prod.ally.ac
- Kanadan palvelinkeskus: prod-ca-central-1.ally.ac
- Euroopan palvelinkeskus: prod-eu-central-1.ally.ac
- Singaporen palvelinkeskus: prod-ap-southeast-1.ally.ac
- Australian palvelinkeskus: prod-ap-southeast-2.ally.ac
Edellä mainitut tiedot voivat vaihdella LMS:stä riippuen. Voit tarkistaa sarakkeen määritelmän kunkin LMS-järjestelmän kurssiraporttia käsittelevästä dokumentaatiosta:
HTTP-tilavastaus
Ally-ohjelmointirajapintan metatiedoissa on seuraava tilakenttä:
- Status 200 - Successful: Pyyntösi vastaanotettiin onnistuneesti ja pyydetty tietojoukko on osa vastausta.
- Status 202 - Processing: Pyyntösi vastaanotettiin onnistuneesti, mutta tietojoukkoa valmistellaan, eikä se ole vielä käytettävissä. Toista pyyntösi jonkin ajan kuluttua (suosituksena on vähintään minuutti).
- Status 401 - Unauthorized: Ally-asiakastunnus tai valtuutustunnus ei ole oikein.
- Status 400 - Bad request: URL-osoitteessa on virheellinen parametrin nimi, kuten tuntematon suodatusvaihtoehto, operaattori tai arvo. Tarkista URL-osoitteen syntaksi. Ota huomioon, että kirjainkoko otetaan huomioon osassa suodatus- ja laijitteluvaihtoehdoista .
Menetelmien dokumentointi
Metodi: Overall
HTTP-pyyntö: GET
https:// [Alue]/api/v2/clients/[Ally-asiakastunnus]/reports/overall
Korvaa [Ally-asiakastunnus] omalla Ally-tuunnuksellasi. Jos et tiedä tunnustasi, voit pyytää sen luomalla tukipyynnön.
Korvaa [Alue] sen mukaan, millä alueella oppilaitoksesi Ally-ympäristöä isännöidään:
- Yhdysvaltain palvelinkeskus: prod.ally.ac
- Kanadan palvelinkeskus: prod-ca-central-1.ally.ac
- Euroopan palvelinkeskus: prod-eu-central-1.ally.ac
- Singaporen palvelinkeskus: prod-ap-southeast-1.ally.ac
- Australian palvelinkeskus: prod-ap-southeast-2.ally.ac
Valtuutus: OAuth-haltijatunniste.
Parametrit: Valinnaiset suodattimet tai lajitteluvaihtoehdot.
Pyynnön runko: Ei mitään
Vastaus:nbsp;
{
"data": [
{
"application/x-quiz": 2,
"observedDeletedOn": "",
"termName": "Fall 2016",
"courseId": "1",
"application/x-announcement": 0,
"image": 4,
"termId": "2",
"document": 93,
"allyEnabled": true,
"pdf": 74,
"courseCode": "BIO101",
"application/x-assignment": 0,
"departmentId": "1",
"totalFiles": 192,
"courseUrl": "https://ally.instructure.com/courses/1",
"departmentName": "Anthology Ally",
"application/x-page": 1,
"filesScore": 0.6022810739019293,
"application/x-syllabus": 1,
"numberOfStudents": 1,
"html-page": 5,
"lastCheckedOn": "2022-04-13 15:33:23",
"WYSIWYGScore": 1.0,
"totalWYSIWYG": 5,
"courseName": "Biology 101",
"application/x-discussion-topic": 1,
"other": 11,
"overallScore": 0.6129724428830603,
"presentation": 5
}
],
"metadata": {
"filteredTotal": 0,
"total": 7186,
"to": 7186,
"status": "Processing",
"from": 1
}
}
Metodi: Issues
HTTP-pyyntö: GET
https:// [Alue]/api/v2/clients/[Ally-asiakastunnus]/reports/overall
Korvaa [Ally-asiakastunnus]-tunnus Ally-tunnuksellasi. Jos et tiedä tunnustasi, voit pyytää sen luomalla tukipyynnön.
Korvaa [Alue] sen mukaan, millä alueella oppilaitoksesi Ally-ympäristöä isännöidään:
- Yhdysvaltain palvelinkeskus: prod.ally.ac
- Kanadan palvelinkeskus: prod-ca-central-1.ally.ac
- Euroopan palvelinkeskus: prod-eu-central-1.ally.ac
- Singaporen palvelinkeskus: prod-ap-southeast-1.ally.ac
- Australian palvelinkeskus: prod-ap-southeast-2.ally.ac
Valtuutus: OAuth-haltijatunniste
Parametrit: valinnaiset suodattimet tai lajitteluvaihtoehdot.
Pyynnön teksti: ei mitään
Vastaus:
{
"data": [
{
"imageDecorative2": 4,
"htmlEmptyHeading2": 0,
"imageSeizure1": 2,
"observedDeletedOn": "",
"htmlObjectAlt2": 0,
"security1": 3,
"termName": "Fall 2016",
"courseId": "1",
"languageCorrect3": 14,
"htmlColorContrast2": 2,
"htmlLinkName3": 0,
"termId": "2",
"languagePresence3": 10,
"allyEnabled": true,
"htmlLabel2": 0,
"alternativeText2": 68,
"htmlImageAlt2": 0,
"htmlImageRedundantAlt3": 0,
"headingsPresence2": 20,
"courseCode": "BIO101",
"headingsSequential3": 4,
"departmentId": "1",
"htmlHeadingsPresence2": 0,
"courseUrl": "https://ally.instructure.com/courses/1",
"headingsStartAtOne3": 4,
"departmentName": "Anthology Ally",
"htmlHeadingsStart2": 0,
"htmlTdHasHeader2": 0,
"htmlList3": 0,
"htmlDefinitionList3": 0,
"htmlCaption2": 0,
"tableHeaders2": 23,
"htmlEmptyTableHeader2": 0,
"htmlHasLang3": 1,
"ocred2": 0,
"scanned1": 6,
"htmlBrokenLink2": 0,
"numberOfStudents": 1,
"htmlHeadingOrder3": 0,
"lastCheckedOn": "2022-04-13 15:33:23",
"headingsHigherLevel3": 0,
"contrast2": 28,
"title3": 46,
"imageOcr3": 0,
"tagged2": 4,
"libraryReference": 172,
"courseName": "Biology 101",
"imageContrast2": 0,
"imageDescription2": 4,
"htmlTitle3": 1,
"parsable1": 2
}
],
"metadata": {
"filteredTotal": 0,
"total": 7186,
"to": 7186,
"status": "Processing",
"from": 1
}
}
Where:
- data: sisältää tulosten tietojoukon.
- Metadata:
- to: tietue, johon tiedot noudetaan; se on "offset" + "limit" tai "total", jos summa on suurempi kuin "total".
- from: tietue, josta tiedot alkavat; se on "offset" + 1.
- total: Allyn LMS-esiintymässä huomioon ottamien kurssien kokonaismäärä.
Offset-parametri: mistä tietueesta aloitetaan
- ensimmäinen rivi: offset = 0
- kun offset < 0, käyttäjä saa 400-virheen: [Invalid value (parameter=offset, message=No such data)],
- kun (offset >= total) => käyttäjä saa 400-virheen: [Invalid value (parameter=offset, message=No such data)]
Limit-parametri: kuinka monta tietuetta noudetaan offset-parametrista alkaen
- kun (limit < 1), käyttäjä saa 400-virheen: [Invalid value (parameter=limit, message=Limit out of boundaries)]
- kun (limit >nbsp;10000), käyttäjä saa 400-virheen: [Invalid value (parameter=limit, message=Limit out of boundaries)]
- kun (offset < total && offset + limit > total), muutamme rajaa taustalla puolestasi, ja tiedot noudetaan viimeiseen elementtiin asti (total)
Suodattimet ja lajitteluvaihtoehdot
Päätepistevastaukset voidaan suodattaa URL-osoitteessa. Tässä osiossa kuvataan käytettävissä olevat vaihtoehdot:
Lajitteluvaihtoehdot
Voit määrittää, haluatko näyttää tulokset lajiteltuina nousevaan vai laskevaan järjestykseen yhden ehdon perusteella. Jos sinun on lisättävä lajitteluvaihtoehto, sinun on lisättävä lajitteluparametri alla kuvatulla tavalla:
endpoint-url?sort=<Sort parameter value>
jossa <Sort parameter value> voi olla mikä tahansa seuraavista parametriarvoista:
| Parametriarvo | Kuvaus | Missä tuetaan | Esimerkki |
| courseName | Lajittele kurssin nimen mukaan, esimerkiksi Kemian perusteet (courseCode ei ole kelvollinen) | Päätepisteet Overall ja Issuesnbsp; | endpoint-url?sort=courseName |
| courseId | Lajittele kurssitunnuksen mukaan, esimerkiksi 123456 (tämä on yleensä kokonaisluku) | Päätepisteet Overall ja Issues | endpoint-url?sort=courseId |
| termId | Lajittelu lukukausitunnuksen mukaan. Esimerkiksi Sum | Päätepisteet Overall ja Issues | endpoint-url?sort=termId |
| termName | Lajittelu lukukauden nimen mukaan, kuten kesä | Päätepisteet Overall ja Issues | endpoint-url?sort=termName |
| overallScore | Lajittelu kunkin kurssin yleisen helppokäyttöisyysarvon mukaan. | Vain Overall-päätepiste. | endpoint-url?sort=overallScore |
| filesScore | Tulosten lajittelu kunkin kurssin tiedostopistemäärän mukaan. | Vain Overall-päätepiste. | endpoint-url?sort=filesScore |
| wysiwygScore | Tulosten lajittelu kunkin kurssin WYSIWYG-pistemäärän mukaan. | Overall-päätepiste ja käytettävissä vain Ally for LMS:ssä. | endpoint-url?sort= wysiwygScore |
| webPagesScore | Tulosten lajittelu kunkin verkkotunnuksen verkkosivupistemäärän mukaan. | Overall-päätepiste ja käytettävissä vain Ally for Webissä ja WCM:ssä. | endpoint-url?sort= webPagesScore |
Kirjainkoko otetaan huomioon parametrien arvoissa, ja kerrallaan voidaan käyttää vain yhtä lajitteluvaihtoehtoa.
Tulokset lajitellaan oletusarvoisesti nousevaan järjestykseen. Jos haluat määrittää toisen järjestyksen, voit lisätä order-parametrin:
endpoint-url?sort=<Sort parameter value>&order=<Order value>
jossa <Order value> voi olla: asc tai desc
Esimerkki:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Suodatusvaihtoehdot
Suodatusvaihtoehtojen avulla voit saada pienempiä tai vähemmän vastauksia valittujen perusteiden mukaan. Jos sinun on lisättävä suodatusvaihtoehto, siniun on lisättävä suodatusparametri seuraavien ohjeiden mukaisesti:
Suodatinparametrit (ilman operaattoria)
| Suodatinparametrin nimi | Kuvaus | Missä tuetaan |
| allyEnabled | Saat tulokseksi kurssit, joissa Ally on käytössä Arvo on tosi tai epätosi | Overall- ja Issues-päätepisteet |
| departmentId | Suodatus osastotunnuksen mukaan | Päätepisteet Overall ja Issues |
| departmentName | Suodatus osaston nimen mukaan. esim. tekninen suunnittelu | Päätepisteet Overall ja Issues |
| termId | Suodatus lukukausitunnuksen mukaan | Päätepisteet Overall ja Issues |
| termName | Suodatus lukukauden nimen mukaan, kuten kesä | Päätepisteet Overall ja Issues |
| courseId | Suodata tunnuksen tai kurssin mukaan. esim. 123456 (tämä on yleensä kokonaisluku) | Päätepisteet Overall ja Issues |
| courseName | Suodatus kurssin nimen mukaan. Esimerkiksi Kemian perusteet (courseCode ei ole kelvollinen) | Päätepisteet Overall ja Issues |
endpoint-url?<Filter Parameter>=<value>
Suodatinparametrit (operaattorin kanssa)
endpoint-url?<Filter Parameter>=<Operator>:<value>
Where:
- <Filter Parameter>: suodatusparametri pienemmän tulosjoukon saamiseksi. Tuetut parametrit esitetään alla olevassa taulukossa.
- <Operator>: suodatuksessa on käytettävä operaattoria, kuten yhtä suuri kuin tai erisuuri kuin.
- <value>: Suodattimessa käytetty arvo.
| Suodatinparametrin nimi | Kentän tyyppi | Tuetut operaattoritnbsp; | Kuvausnbsp; | Missä tuetaan |
| allyEnabled | boolean | eq, ne | Saat tulokseksi kurssit, joissa Ally on käytössä. Arvo on tosi tai epätosi. | Päätepisteet Overall ja Issues |
| courseName | merkkijono | eq, ne, co, nc, sw | Suodatus kurssin nimen mukaan. Esimerkiksi Kemian perusteet (courseCode ei ole kelvollinen) | Päätepisteet Overall ja Issues |
| courseId | merkkijono | eq, ne, co, nc, sw | Suodata tunnuksen tai kurssin mukaan. Esimerkiksi 123456 (tämä on yleensä kokonaisluku) | Päätepisteet Overall ja Issues |
| termId | merkkijono | eq, ne, co, nc, sw | Suodatus lukukausitunnuksen mukaan. | Päätepisteet Overall ja Issues |
| termName | merkkijono | eq, ne, co, nc, sw | Suodatus lukukauden nimen mukaan, kuten kesä | Päätepisteet Overall ja Issues |
| overallScore | luku | eq, ne, le, lt, ge, gt | Voit suodattaa kokonaispistemäärän mukaan, esimerkiksi kurssit, joiden pistemäärä on 90 % | Overall-päätepiste ja kaikissa Ally-ratkaisuissa: LMS, verkkosivustot ja WCM. |
| filesScore | luku | eq, ne, le, lt, ge, gt | Voit suodattaa tiedostojen pistemäärän mukaan, esim. kurssit, joiden tiedostojen pistemäärä on 90 % | Overall-päätepiste ja kaikissa Ally-ratkaisuissa: LMS, verkkosivustot ja WCM. |
| wysiwygScore | luku | eq, ne, le, lt, ge, gt | Voit suodattaa WYSIWYG-pistemäärän mukaan, esim. kurssit, joiden WYSIWYG-pistemäärä on 90 % | Overall-päätepiste ja käytettävissä vain Ally for LMS:ssä. |
| webPagesScore | luku | eq, ne, le, lt, ge, gt | Voit suodattaa verkkotunnuksen pistemäärän mukaan, esim. verkkosivut, joiden pistemäärä on 90 %. | Overall-päätepiste ja käytettävissä vain Ally for Webissä tai WCM:ssä. |
Kirjainkoolla on merkitystä parametrien arvoissa.
Tuetut operaattorit
Seuraavassa taulukossa esitetään tuetut operaattorit kenttätyypin mukaan:
| Kenttätyyppi | Operaattori | Kuvaus |
| merkkijono | eq | Is equal |
| merkkijono | ne | Is not equal |
| merkkijono | co | Contains keyword |
| merkkijono | nc | Does not contains keyword |
| merkkijono | sw | Starts with keyword |
| luku | eq | Is equal |
| luku | ne | Is not equal |
| luku | le | Less than or equal |
| luku | lt | Less than |
| luku | ge | Greater than or equal |
| luku | gt | Greater than |
Esimerkki:
Seuraava esimerkki noutaa kaikki kurssit, joiden kurssinimessä on avainsana "tests":
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Useiden suodattimien käyttäminen
Voit yhdistää samaan päätepiste-URL-osoitteeseen lajittelu- ja suodatusvaihtoehdot lisäämällä "&"-merkin näiden kahden ehdon väliin. Oletetaan esimerkiksi, että haluat noutaa kaikki kurssit, joiden kurssinimessä on avainsana "test", joissa Ally on käytössä ja joiden kokonaispistemäärä on alle 90 %. URL-osoite näyttää tältä:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
Voit myös käyttää kahta suodatusvaihtoehtoa. Oletetaan esimerkiksi, että sinun on noudettava kaikki kurssit, joiden kokonaispistemäärä on 10–70 %:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7
