API-eindpunten rapporteren
API-eindpunten rapporteren
Waarschuwing
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-verzoektype | 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. |
Tip
Vervang [Ally Client ID] door je Ally ID. Als je je ID niet weet, kun je een ondersteuningsticket aanmaken om deze aan te vragen.
Tip
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
Datacenter in Singapore: prod-ap-southeast-1.ally.ac
Datacenters in Singapore: prod-ap-southeast-2.ally.ac
HTTP-statusreactie
De Ally API bevat als volgt een statusveld in de metagegevens:
Status 200 - Succesvol: Uw verzoek is succesvol ontvangen en de gevraagde dataset maakt deel uit van het antwoord.
Status 202 - Verwerkt: Uw verzoek is succesvol ontvangen, maar de dataset is in voorbereiding en nog niet beschikbaar. Herhaal je verzoek na enige tijd (minimaal één minuut wordt aanbevolen).
Status 401 - Ongeautoriseerd: De Ally Client ID of het autorisatietoken zijn niet correct.
Status 400 - Slecht verzoek: De URL heeft een ongeldige parameternaam, bijvoorbeeld een onbekende filteroptie, operator of waarde. Controleer de syntaxis van de URL. Onthoud dat sommige filter- en sorteeropties hoofdlettergevoelig zijn.
Methodendocumentatie
Methode: Algemeen
HTTP-verzoek: GET
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
Datacenter in Singapore: prod-ap-southeast-1.ally.ac
Datacenters in Singapore: prod-ap-southeast-2.ally.ac
Autorisatie: OAuth-token met bearer.
Parameters: Optionele filters of sorteeropties.
Verzoek: Geen
Antwoord:
{
"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
}
} Methode: Problemen
HTTP-verzoek: GET
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
Datacenter in Singapore: prod-ap-southeast-1.ally.ac
Datacenters in Singapore: prod-ap-southeast-2.ally.ac
Autorisatie: OAuth dragertoken
Parameters: optionele filters of sorteeropties.
Verzoek: Geen
Antwoord:
{
"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
}
} Waar:
Data: bevat de dataset van de resultaten.
Metagegevens:
Om: te registreren waaraan de gegevens worden gehaald, het is "offset" + "limiet" of "totaal" als de som hoger is dan "totaal".
Van: het record van welke data begint, het is "offset" + 1.
Totaal: totaal aantal cursussen dat door Ally in de LMS-instantie is overwogen.
Offset - vanaf welke plaat begint
De eerste rij is offset = 0,
Bij begin < 0, krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=begin, message=geen gegevens)],
Wanneer (offset >= totaal) => krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=offset, message=Geen dergelijke gegevens) ]
Limiet - hoeveel records worden opgehaald vanaf offset
Bij (limiet < 1), krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=limiet, message= limiet buiten grenzen)],
Wanneer (limiet > 10000) krijgt de gebruiker fout 400 - [Ongeldige waarde (parameter=limiet, bericht=Limiet buiten grenzen)]
Wanneer (offset < total && offset + limit > totaal), dan veranderen we de limiet op de achtergrond voor u, en worden gegevens opgehaald tot het laatst (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=<Sort parameter value>
Waar <Sorteerparameterwaarde> een van de volgende parameterwaarden kan zijn:
Parameterwaarde | Beschrijving | Ondersteund in | Voorbeeld |
courseName | Sorteer op cursusnaam, bijvoorbeeld Scheikunde 101 (cursuscode is niet geldig) | Eindpunten totaal en problemen | endpoint-url?sort=courseName |
courseId | Sorteer op cursus-ID, bijvoorbeeld 123456 (dit is meestal een geheel getal) | Eindpunten totaal en problemen | endpoint-url?sort=courseId |
termId | Sorteer op semester-ID. Bijvoorbeeld Sum | Eindpunten totaal en problemen | endpoint-url?sort=termId |
termName | Sorteer op term Naam. bijvoorbeeld zomer | Eindpunten totaal 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 |
Opmerking
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=<Sort parameter value>&order=<Order value>
Waar <Orderwaarde> kan zijn: asc of dezes
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 beschreven:
Filterparameters (zonder operator)
Filterparameternaam | 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 | Eindpunten totaal en problemen |
departmentName | Filter op de naam van de afdeling. Bijvoorbeeld Techniek | Eindpunten totaal en problemen |
termId | Filter op de semester-ID | Eindpunten totaal en problemen |
termName | Filter op de naam van de term. bijvoorbeeld zomer | Eindpunten totaal en problemen |
courseId | Filter op ID of cursus. bijvoorbeeld 123456 (dit is meestal een geheel getal) | Eindpunten totaal en problemen |
courseName | Filter op de naam van een cursus. Bijvoorbeeld Scheikunde 101 (cursuscode is niet geldig) | Eindpunten totaal en problemen |
endpoint-url?<Filter Parameter>=<value>
Filterparameters (met operator)
endpoint-url?<Filter Parameter>=<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 wordt gebruikt.
Filterparameternaam | Veldtype | Ondersteunde operators | Beschrijving | Ondersteund in |
allyEnabled | Booleaans | eq, ne | Je kunt de cursussen opvragen waarin Ally actief is. Waarde is waar of onwaar. | Eindpunten totaal en problemen |
courseName | Tekenreeks | eq, ne, co, nc, sw | Filter op de naam van een cursus. Bijvoorbeeld Scheikunde 101 (cursuscode is niet geldig) | Eindpunten totaal en problemen |
courseId | Tekenreeks | eq, ne, co, nc, sw | Filter op de ID of een cursus. Bijvoorbeeld 123456 (dit is meestal een geheel getal) | Eindpunten totaal en problemen |
termId | Tekenreeks | eq, ne, co, nc, sw | Filter op de semester-ID. | Eindpunten totaal en problemen |
termName | Tekenreeks | eq, ne, co, nc, sw | Filter op de naam van de term. bijvoorbeeld zomer | Eindpunten totaal en problemen |
overallScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op een algemene score. bijvoorbeeld cursussen met een score gelijk aan 90% | Algemene endpoint en in alle Ally-oplossingen: LMS, websites en WCM. |
filesScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op de score van het bestand. bijvoorbeeld cursussen met een bestandsscore gelijk aan 90% | Algemene endpoint en in alle Ally-oplossingen: LMS, websites en WCM. |
wysiwygScore | Getal | eq, ne, le, lt, ge, gt | Je kunt filteren op de WYSIWYG-score. bijvoorbeeld 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. |
Opmerking
Parameterwaarden zijn hoofdlettergevoelig.
Ondersteunde operators
De volgende tabel bevat de ondersteunde operators op basis van het veldtype:
Veldtype | Operator | Beschrijving |
Tekenreeks | eq | Is gelijk |
Tekenreeks | Ne | Is niet gelijk |
Tekenreeks | co | Bevat trefwoord |
Tekenreeks | nc | Bevat geen trefwoord |
Tekenreeks | sw | Begint met trefwoord |
Getal | eq | Is gelijk |
Getal | Ne | Is niet gelijk |
Getal | le | Minder dan of gelijk |
Getal | lt | Minder 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
Gebruik van meerdere filters
Je kunt de sorteer- en filteropties in hetzelfde 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