Eindpunten in de API voor rapportage zijn persoonlijke eindpunten en hebben op dit moment geen uitfaseringsbeleid. Anthology Ally kan deze eindpunten wijzigen of bijwerken, afhankelijk van onze planning of toekomstige releases.
Raadpleeg de volgende technische documentatie om te lezen hoe je eindpunten op de juiste manier instelt en aanpast. Controleer hoe je de API van Ally kunt integreren met een externe tool voor rapportage voor aanvullende hulp.
Beschikbare methoden
De Ally API voor rapportage bevat twee methoden. In de volgende sectie worden deze methoden beschreven:
| Methode | URL | HTTP-aanvraagtype | Beschrijving |
| Algemeen | https://[regio]/api/v2/clients/[Ally client-ID]/reports/overall | Ophalen | Deze methode retourneert standaard een gegevensset met informatie over de cursus, WYSIWYG en de scores van bestanden en bestandstypen die worden opgenomen in elke cursus uit de LMS-instantie, ongeacht of Ally is ingeschakeld of niet. |
| Problemen | https://[regio]/api/v2/clients/[Ally client-ID]/reports/issues | Ophalen | Met deze methode wordt standaard een gegevensset geretourneerd met de informatie die gerelateerd is aan alle toegankelijkheidsproblemen van elke cursus, opgenomen in de LMS-instantie, ongeacht of Ally is ingeschakeld of niet. |
Vervang [Ally client-ID] door je Ally-ID. Als je je ID niet weet, kun je een ondersteuningsticket aanmaken om deze aan te vragen.
Vervang [regio] afhankelijk van de regio waarin de Ally-omgeving van je instelling wordt gehost:
- Datacenters in de Verenigde Staten: prod.ally.ac
- Datacenters in Canada: prod-ca-central-1.ally.ac
- Datacenters in Europa: prod-eu-central-1.ally.ac
- Datacenters in Singapore: prod-ap-southeast-1.ally.ac
- Datacenters in Australië: prod-ap-southeast-2.ally.ac
De bovenstaande informatie kan variëren afhankelijk van het LMS. Je kunt de kolomdefinitie bekijken in de rapportagedocumentatie van de cursus voor elk LMS:
HTTP-statusantwoord
De Ally API bevat als volgt een statusveld in de metagegevens:
- Status 200 - Gelukt: Je verzoek is ontvangen en de opgevraagde gegevensset maakt deel uit van de reactie.
- Status 202 - Verwerken: Je aanvraag is ontvangen, maar de gegevensset wordt nog voorbereid en is nog niet beschikbaar. Herhaal je verzoek na enige tijd (minimaal één minuut wordt aanbevolen).
- Status 401 - Onbevoegd: De Ally client-ID of de autorisatietoken is niet correct.
- Status 400 - Onjuist verzoek: De URL heeft een ongeldige parameternaam, bijvoorbeeld een onbekende filteroptie, operator of waarde. Controleer de syntaxis van de URL. Vergeet niet dat sommige filter- en sorteeropties hoofdlettergevoelig zijn.
Documentatie over methoden
Methode: Algemeen
HTTP-aanvraag: OPHALEN
https:// [regio]/api/v2/clients/[Ally client-ID]/reports/overall
Vervang [Ally client-ID] door je Ally-ID. Als je je ID niet weet, kun je een ondersteuningsticket aanmaken om deze aan te vragen.
Vervang [regio] afhankelijk van de regio waarin de Ally-omgeving van je instelling wordt gehost:
- Datacenters in de Verenigde Staten: prod.ally.ac
- Datacenters in Canada: prod-ca-central-1.ally.ac
- Datacenters in Europa: prod-eu-central-1.ally.ac
- Datacenters in Singapore: prod-ap-southeast-1.ally.ac
- Datacenters in Australië: prod-ap-southeast-2.ally.ac
Autorisatie: OAuth-token met bearer.
Parameters: optionele filters of sorteeropties.
Tekst van aanvraag: geen
Antwoord:
{
"data": [
{
"application/x-quiz": 2,
"observedDeletedOn": "",
"termName": "Najaar 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": "Biologie 101",
"application/x-discussion-topic": 1,
"other": 11,
"overallScore": 0.6129724428830603,
"presentation": 5
}
],
"metadata": {
"filteredTotal": 0,
"total":7186,
"to":7186,
"status":"Verwerken",
"from": 1
}
}
Methode: Problemen
HTTP-aanvraag: OPHALEN
https:// [regio]/api/v2/clients/[Ally client-ID]/reports/overall
Vervang [Ally client-ID] ID door je Ally-ID. Als je je ID niet weet, kun je een ondersteuningsticket aanmaken om deze aan te vragen.
Vervang [regio] afhankelijk van de regio waarin de Ally-omgeving van je instelling wordt gehost:
- Datacenters in de Verenigde Staten: prod.ally.ac
- Datacenters in Canada: prod-ca-central-1.ally.ac
- Datacenters in Europa: prod-eu-central-1.ally.ac
- Datacenters in Singapore: prod-ap-southeast-1.ally.ac
- Datacenters in Australië: prod-ap-southeast-2.ally.ac
Autorisatie: OAuth-token met bearer
Parameters: optionele filters of sorteeropties.
Tekst van aanvraag: geen
Antwoord:
{
"data": [
{
"imageDecorative2": 4,
"htmlEmptyHeading2":0,
"imageSeizure1":2,
"observedDeletedOn": "",
"htmlObjectAlt2":0,
"security1": 3,
"termName":"Najaar 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": "Biologie 101",
"imageContrast2":0,
"imageDescription2":4,
"htmlTitle3":1,
"parsable1":2
}
],
"metadata": {
"filteredTotal":0,
"total":7186,
"to":7186,
"status":"Verwerken",
"from":1
}
}
Waar:
- Gegevens: bevat de gegevensset van de resultaten.
- Metagegevens:
- Aan: record waarvoor gegevens worden opgehaald; als de som meer dan het ‘totaal’ is, is het ‘begin’ + ‘limiet’ of ‘totaal’.
- Van: record van waaruit de gegevens beginnen; deze is ‘begin’ + 1.
- Totaal: totale aantal cursussen dat door Ally is beoordeeld in de LMS-instantie.
Begin - waarvandaan de record begint
- Eerste rij is begin = 0,
- Bij begin < 0, krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=begin, message=geen gegevens)],
- Bij (begin >= totaal) => krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=begin, message=geen gegevens)]
Limiet - hoeveel records er worden opgehaald vanaf het begin
- Bij (limiet < 1), krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=limiet, message= limiet buiten grenzen)],
- Bij (limiet > 10000) krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=limiet, message= limiet buiten grenzen)]
- Wanneer (begin < total && begin + limiet > totaal), veranderen we de limiet op de achtergrond voor je en worden gegevens opgehaald tot het laatste (totaal)
Filters en sorteeropties
Antwoorden op eindpunten kunnen gefilterd worden in de URL. In deze sectie worden de beschikbare opties beschreven:
Sorteeropties
Je kunt definiëren of je de resultaten in oplopende of aflopende volgorde gesorteerd wilt weergeven, waarbij rekening wordt gehouden met één criterium. Als je een sorteeroptie wilt toevoegen, moet je de sorteerparameter toevoegen zoals hieronder is beschreven:
endpoint-url?sort=<Sorteer parameterwaarde>
Waarbij <Sorteer parameterwaarde> een van de volgende parameterwaarden kan zijn:
| Parameterwaarde | Beschrijving | Ondersteund in | Voorbeeld |
| cursusnaam | Sorteer op cursusnaam bijv. scheikunde 101 (courseCode is niet geldig) | De eindpunten Algemeen en Problemen | endpoint-url?sort=courseName |
| courseId | Sorteer op cursus-ID, bijv. 123456 (dit is meestal een geheel getal) | De eindpunten Algemeen en Problemen | endpoint-url?sort=courseId |
| termId | Sorteren op semester-ID. Bijvoorbeeld: Som | De eindpunten Algemeen en Problemen | endpoint-url?sort=termId |
| termName | Sorteer op semesternaam, bijv. zomer | De eindpunten Algemeen en Problemen | endpoint-url?sort=termName |
| overallScore | Sorteer op de globale toegankelijkheidsscore van elke cursus. | Alleen totaaleindpunt. | endpoint-url?sort=overallScore |
| filesScore | Sorteer de resultaten op de bestandsscore van elke cursus. | Alleen totaaleindpunt. | endpoint-url?sort=filesScore |
| wysiwygScore | Sorteer de resultaten op de WYSIWYG-score van elke cursus. | Totaaleindpunt en alleen beschikbaar voor Ally voor LMS. | endpoint-url?sort= wysiwygScore |
| webPagesScore | Sorteer de resultaten op webpaginascore van elk domein. | Totaaleindpunt en alleen beschikbaar voor Ally voor Web en WCM. | endpoint-url?sort= webPagesScore |
Parameterwaarden zijn hoofdlettergevoelig en er kan slechts één sorteeroptie tegelijk worden gebruikt.
De resultaten worden standaard gesorteerd in oplopende volgorde. Als je een andere volgorde wilt instellen, kun je de volgordeparameter toevoegen:
endpoint-url?sort=<Sorteer parameterwaarde>&order=<Volgordewaarde>
Waarbij <Volgordewaarde> een van de volgende kan zijn: opl of afl
Voorbeeld:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Filteropties
Je kunt filteropties gebruiken om kleinere of verkorte antwoorden te verkrijgen op basis van de geselecteerde criteria. Als je een filteroptie moet toevoegen, moet je de filterparameter toevoegen zoals hieronder is beschreven:
Filterparameters (zonder operator)
| Naam filterparameter | Beschrijving | Ondersteund in |
| allyEnabled | Je kunt de cursussen opvragen waarin Ally actief is Waarde is waar of onwaar | Eindpunten totaal en problemen |
| departmentId | Filter op afdelings-ID | De eindpunten Algemeen en Problemen |
| departmentName | Filter op afdelingsnaam, bijv. engineering | De eindpunten Algemeen en Problemen |
| termId | Filter op de semester-ID | De eindpunten Algemeen en Problemen |
| termName | Filter op de semesternaam, bijv. zomer | De eindpunten Algemeen en Problemen |
| courseId | Filter op de ID of een cursus. bijv. 123456 (dit is meestal een geheel getal) | De eindpunten Algemeen en Problemen |
| cursusnaam | Filter op de naam van een cursus. Bijvoorbeeld: Scheikunde 101 (courseCode is niet geldig) | De eindpunten Algemeen en Problemen |
endpoint-url?<Filterparameter>=<value>
Filterparameters (zonder operator)
endpoint-url?<Filterparameter>=<Operator>:<value>
Waar:
- <Filterparameter>: Filterparameter om een kleinere set resultaten te krijgen. Je kunt de ondersteunde parameters in de onderstaande tabel raadplegen.
- <Operator>: Je moet een operator gebruiken om te filteren, zoals gelijk, niet gelijk.
- <waarde>: Waarde die in het filter is gebruikt.
| Naam filterparameter | Veldtype | Ondersteunde operators | Beschrijving | Ondersteund in |
| allyEnabled | Booleaans | eq, ne | Je kunt de cursussen opvragen waarin Ally actief is Waarde is waar of onwaar | De eindpunten Algemeen en Problemen |
| courseName | Tekenreeks | eq, ne, co, nc, sw | Filter op de naam van een cursus. Bijvoorbeeld: Scheikunde 101 (courseCode is niet geldig) | De eindpunten Algemeen en Problemen |
| courseId | Tekenreeks | eq, ne, co, nc, sw | Filter op de ID of een cursus. Bijv. 123456 (dit is meestal een geheel getal) | De eindpunten Algemeen en Problemen |
| termId | Tekenreeks | eq, ne, co, nc, sw | Filter op de semester-ID. | De eindpunten Algemeen en Problemen |
| termName | Tekenreeks | eq, ne, co, nc, sw | Filter op de semesternaam, bijv. zomer | De eindpunten Algemeen en Problemen |
| overallScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op een totaalscore, bijv. cursussen met een score gelijk aan 90% | Totaaleindpunt en in alle Ally-oplossingen: LMS, websites en WCM. |
| filesScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op de bestandsscore, bijv. cursussen met een bestandsscore gelijk aan 90% | Totaaleindpunt en in alle Ally-oplossingen: LMS, websites en WCM. |
| wysiwygScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op de WYSIWYG-score, bijv. cursussen met een WYSIWYG score gelijk aan 90% | Totaaleindpunt en alleen beschikbaar voor Ally voor LMS. |
| webPagesScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op de score van een domein, bijv. webpagina's met een score gelijk aan 90%. | Totaaleindpunt en alleen beschikbaar voor Ally voor Web of WCM. |
Parameterwaarden zijn hoofdlettergevoelig.
Ondersteunde operators
De volgende tabel bevat de ondersteunde operators op basis van het veldtype:
| Veldtype | Operator | Beschrijving |
| Tekenreeks | Eq | Is gelijk aan |
| Tekenreeks | Ne | Is niet gelijk |
| Tekenreeks | co | Bevat trefwoord |
| Tekenreeks | nc | Bevat geen trefwoord |
| Tekenreeks | sw | Begint met trefwoord |
| Getal | Eq | Is gelijk aan |
| Getal | Ne | Is niet gelijk |
| Getal | le | Kleiner dan of gelijk |
| Getal | lt | Kleiner dan |
| Getal | ge | Groter dan of gelijk |
| Getal | gt | Groter dan |
Voorbeeld:
In het volgende voorbeeld worden alle cursussen opgehaald die het trefwoord 'toetsen' in de cursusnaam hebben:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Meerdere filters gebruiken
Je kunt de sorteer- en filteropties in dezelfde eindpunt-URL combineren door het teken '&' toe te voegen tussen de twee voorwaarden. Stel dat je alle cursussen met het trefwoord 'toets' in de cursusnaam wilt ophalen waar Ally is ingeschakeld, en dat de totaalscore lager is dan 90%. De URL ziet er dan zo uit:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
Je kunt ook twee filteropties gebruiken. Stel dat je alle cursussen moet ophalen met een totaalscore tussen 10% en 70%:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7
