Skip to main content

Berichterstellungs-API-Endpunkte

Berichterstellungs-API-Endpunkte

Warnung

Endpunkte, die in der API für die Berichterstellung enthalten sind, sind private Endpunkte und unterliegen derzeit keiner Alterungsrichtlinie. Anthology Ally kann diese Endpunkte je nach unserer Roadmap oder in zukünftigen Versionen ändern oder aktualisieren.

Lesen Sie die folgende technische Dokumentation, um zu erfahren, wie Sie Ihre Endpunkte entsprechend einrichten und anpassen. Weitere Informationen finden Sie unter Ally-API in ein externes Berichtstool integrieren.Ally-API in ein externes Berichtstool integrieren

Verfügbare Methoden

Für die Ally-API für die Berichterstellung gibt es zwei Methoden. Im folgenden Abschnitt werden sie beschrieben:

Methode

URL

HTTP-Anforderungstyp

Beschreibung

Overall

https://[Region]/api/v2/clients/[Ally-Client-ID]/reports/overall

Get

Standardmäßig gibt diese Methode ein Dataset mit Informationen zum Kurs, WYSIWYG sowie den Ergebnissen und Dateitypen der Dateien zurück, die in jedem Kurs der LMS-Instanz enthalten sind, unabhängig davon, ob Ally aktiviert ist oder nicht.

Issues

https://[Region]/api/v2/clients/[Ally-Client-ID]/reports/issues

Get

Standardmäßig gibt diese Methode ein Dataset mit Informationen zu allen Problemen mit der Barrierefreiheit in jedem Kurs zurück, der in der LMS-Instanz enthalten ist, unabhängig davon, ob Ally aktiviert ist oder nicht.

Tipp

Ersetzen Sie [Ally-Client-ID] durch Ihre Ally-ID. Wenn Sie Ihre ID nicht kennen, können Sie ein Support-Ticket erstellen, um sie anzufordern.

Tipp

Ersetzen Sie [Region] abhängig von der Region, in der die Ally-Umgebung Ihrer Institution gehostet wird:

HTTP-Status-Antwort

Die Ally-API enthält in den Metadaten ein Statusfeld:

  • Status 200 - Erfolgreich: Ihre Anforderung wurde erfolgreich empfangen, und das angeforderte Dataset ist Teil der Antwort.

  • Status 202 - Verarbeitung: Ihre Anfrage wurde erfolgreich empfangen, aber der Datensatz befindet sich in Vorbereitung und ist noch nicht verfügbar. Wiederholen Sie Ihre Anfrage nach einiger Zeit (empfohlen wird mindestens eine Minute).

  • Status 401 - Nicht autorisiert: Die Ally-Client-ID oder das Autorisierungstoken sind nicht korrekt.

  • Status 400 - Ungültige Anforderung: Die URL hat einen ungültigen Parameternamen, z. B. eine unbekannte Filteroption, einen unbekannten Operator oder Wert. Überprüfen Sie die Syntax der URL. Denken Sie daran, dass bei einigen Filter- und Sortieroptionen zwischen Groß- und Kleinschreibung unterschieden wird.

Methodendokumentation

Methode: Insgesamt 

HTTP-Anforderung: GET

https:// [Region]/api/v2/clients/[Ally-Client-ID]/reports/overall

Ersetzen Sie [Ally-Client-ID] durch Ihre Ally-ID. Wenn Sie Ihre ID nicht kennen, können Sie ein Support-Ticket erstellen, um sie anzufordern.

Ersetzen Sie [Region] abhängig von der Region, in der die Ally-Umgebung Ihrer Institution gehostet wird:

Autorisierung: OAuth-Bearer-Token.

Parameter: Optionale Filter oder Sortieroptionen.

Anfragetext: Keine

Antwort: 

{ 
    "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: Probleme

HTTP-Anforderung: GET 

https:// [Region]/api/v2/clients/[Ally-Client-ID]/reports/overall

Ersetzen Sie [Ally-Client-ID] durch Ihre Ally-ID. Wenn Sie Ihre ID nicht kennen, können Sie ein Support-Ticket erstellen, um sie anzufordern.

Ersetzen Sie [Region] abhängig von der Region, in der die Ally-Umgebung Ihrer Institution gehostet wird:

Autorisierung: OAuth-Bearertoken 

Parameter: Optionale Filter oder Sortieroptionen.

Anfragetext: Keine

Antwort: 

{ 
    "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 
    } 
}

Wobei gilt:

  • Daten: Enthält den Datensatz der Ergebnisse.

  • Metadaten:

    • An: Datensatz, zu dem die Daten abgerufen werden, es ist "offset" + "limit" oder "total", wenn die Summe "total" überschreitet.

    • Von: Datensatz, von dem aus die Daten beginnen, es ist "offset" + 1.

    • Gesamt: Gesamtzahl der Kurse, die von Ally in der LMS-Instanz berücksichtigt wurden.

Offset - ab welchem Datensatz beginnt

  • Die erste Zeile ist Offset = 0,

  • Wenn Offset < 0, dann erhält der Benutzer den Fehler 400: [Ungültiger Wert (Parameter=Offset, Meldung=Keine solchen Daten)],

  • Wenn (offset >= total) => dann erhält der Benutzer den Fehler 400 - [Ungültiger Wert (parameter=offset, message=No such data) ]

Limit - wie viele Datensätze ab Offset abgerufen werden 

  • Bei (Limit < 1) erhält der Benutzer den Fehler 400: [Ungültiger Wert (Parameter = Limit, Meldung = Limit außerhalb des Grenzwerts)]

  • Wenn (Limit > 10000), erhält der Benutzer den Fehler 400 - [Ungültiger Wert (parameter=limit, message=Limit außerhalb der Grenzen)]

  • Wenn (Offset < total && offset + limit > Total), dann ändern wir das Limit im Hintergrund für Sie, und die Daten werden bis zum Schluss (Total) abgerufen

Filter und Sortieroptionen

Endpunktantworten können in der URL gefiltert werden. In diesem Abschnitt werden die verfügbaren Optionen beschrieben:

Sortieroptionen

Sie können festlegen, ob Sie die Ergebnisse nach einem Kriterium aufsteigend oder absteigend sortiert anzeigen möchten. Wenn Sie eine Sortieroption hinzufügen, müssen Sie den Sortierparameter wie unten beschrieben hinzufügen:

endpoint-url?sort=<Sort parameter value>

Dabei kann <Parameterwert sortieren> einer der folgenden Parameterwerte sein:

Parameter-Wert

Beschreibung

Unterstützt in

Beispiel

courseName

Sortierung nach Kursname, z.B. Chemie 101

(courseCode ist nicht gültig)

Overall- und Issues-Endpunkte

endpoint-url?sort=courseName

courseId

Sortierung nach Kurs-ID, z.B. 123456

(dies ist in der Regel eine ganze Zahl)

Overall- und Issues-Endpunkte

endpoint-url?sort=courseId

termId

Nach Kursabschnitts-ID sortieren. Z.B. Summe

Overall- und Issues-Endpunkte

endpoint-url?sort=termId

termName

Sortieren nach Begriff Name. z.B. Sommer

Overall- und Issues-Endpunkte

endpoint-url?sort=termName

overallScore

Nach der Gesamtbewertung der Barrierefreiheit für jeden Kurs sortieren.

Nur Overall-Endpunkt.

endpoint-url?sort=overallScore

filesScore

Sortieren Sie die Ergebnisse nach der Dateibewertung der einzelnen Kurse.

Nur Overall-Endpunkt.

endpoint-url?sort=filesScore

wysiwygScore

Sortieren Sie die Ergebnisse nach der WYSIWYG-Bewertung der einzelnen Kurse.

Overall-Endpunkt und nur für Ally für LMS verfügbar.

endpoint-url?sort= wysiwygScore

webPagesScore

Sortieren Sie die Ergebnisse nach der Webseiten-Bewertung der einzelnen Domains.

Overall-Endpunkt und nur für Ally für Web und WCM verfügbar.

endpoint-url?sort= webPagesScore

Anmerkung

Bei Parameterwerten wird zwischen Groß- und Kleinschreibung unterschieden, und es kann jeweils nur eine Sortieroption verwendet werden.

Standardmäßig werden die Ergebnisse in aufsteigender Reihenfolge sortiert. Wenn Sie eine andere Reihenfolge festlegen möchten, können Sie den Order-Parameter hinzufügen:

endpoint-url?sort=<Sort parameter value>&order=<Order value>

Dabei kann <Bestellwert> sein: asc oder desc

Beispiel:

https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc

Filtermöglichkeiten

Sie können Filteroptionen verwenden, um kleinere oder reduzierte Ergebnisse basierend auf den ausgewählten Kriterien zu erhalten. Wenn Sie eine Filteroption hinzufügen müssen, müssen Sie den Filterparameter wie unten beschrieben hinzufügen:

Filterparameter (ohne Bediener)

Name des Filterparameters

Beschreibung

Unterstützt in

allyEnabled

Sie können die Kurse abrufen, in denen Ally aktiv ist

Wert ist wahr oder falsch

Overall- und Issues-Endpunkte

departmentId

Nach Abteilungs-ID filtern

Overall- und Issues-Endpunkte

departmentName

Filtern Sie nach dem Namen der Abteilung. z.B. Ingenieurwesen

Overall- und Issues-Endpunkte

termId

Nach Kursabschnitts-ID filtern

Overall- und Issues-Endpunkte

termName

Filtern Sie nach dem Namen des Begriffs. z.B. Sommer

Overall- und Issues-Endpunkte

courseId

Filtern Sie nach der ID oder einem Kurs. z.B. 123456

(dies ist in der Regel eine ganze Zahl)

Overall- und Issues-Endpunkte

courseName

Nach dem Namen eines Kurses filtern. z.B. Chemie 101

(courseCode ist nicht gültig)

Overall- und Issues-Endpunkte

endpoint-url?<Filter Parameter>=<value>

Filterparameter (mit Operator)

endpoint-url?<Filter Parameter>=<Operator>:<value>

Wobei gilt:

  • <Filterparameter>: Filterparameter, um eine kleinere Menge von Ergebnissen zu erhalten. Sie können die unterstützten Parameter in der folgenden Tabelle sehen.

  • <Operator>: Sie müssen einen Operator verwenden, um zu filtern, z. B. gleich, nicht gleich.

  • <value>: Wert, der im Filter verwendet wird.

Name des Filterparameters

Feldtyp

Unterstützte Operatoren

Beschreibung

Unterstützt in

allyEnabled

Boolesch

eq, ne (gleich/ungleich)

Sie können die Kurse abrufen, in denen Ally aktiv ist.

Wert ist wahr oder falsch.

Overall- und Issues-Endpunkte

courseName

Zeichenfolge

EQ, NE, CO, NC, SW

Nach dem Namen eines Kurses filtern. z.B. Chemie 101

(courseCode ist nicht gültig)

Overall- und Issues-Endpunkte

courseId

Zeichenfolge

EQ, NE, CO, NC, SW

Filtern Sie nach ID oder Kurs. Z.B. 123456

(dies ist in der Regel eine ganze Zahl)

Overall- und Issues-Endpunkte

termId

Zeichenfolge

EQ, NE, CO, NC, SW

Nach Kursabschnitts-ID filtern.

Overall- und Issues-Endpunkte

termName

Zeichenfolge

EQ, NE, CO, NC, SW

Filtern Sie nach dem Namen des Begriffs. z.B. Sommer

Overall- und Issues-Endpunkte

overallScore

Zahl

EQ, NE, LE, LT, GE, GT

Sie können nach einer Gesamtbewertung filtern. z.B. Kurse mit einer Punktzahl von 90%

Gesamtendpunkt und in allen Ally-Lösungen: LMS, Websites und WCM.

filesScore

Zahl

EQ, NE, LE, LT, GE, GT

Sie können nach der Dateibewertung filtern. z.B. Kurse mit einer Dateipunktzahl von 90%

Gesamtendpunkt und in allen Ally-Lösungen: LMS, Websites und WCM.

wysiwygScore

Zahl

EQ, NE, LE, LT, GE, GT

Sie können nach dem WYSIWYG-Ergebnis filtern. z.B. Kurse mit einer WYSIWYG-Punktzahl von 90%

Overall-Endpunkt und nur für Ally für LMS verfügbar.

webPagesScore

Zahl

EQ, NE, LE, LT, GE, GT

Sie können nach der Bewertung einer Domäne filtern, z. B. Webseiten mit einer Punktzahl von 90 %.

Gesamtendpunkt und nur für Ally für Web oder WCM verfügbar.

Anmerkung

Bei Parameterwerten wird zwischen Groß- und Kleinschreibung unterschieden.

Unterstützte Operatoren

Die folgende Tabelle enthält die unterstützten Operatoren basierend auf dem Feldtyp:

Feldtyp

Operator

Beschreibung

Zeichenfolge

eq

Ist gleich

Zeichenfolge

ne

Ist nicht gleich

Zeichenfolge

co

Enthält das Schlüsselwort

Zeichenfolge

nc

Enthält kein Schlüsselwort

Zeichenfolge

sw

Beginnt mit Schlüsselwort

Zahl

eq

Ist gleich

Zahl

ne

Ist nicht gleich

Zahl

le

Kleiner oder gleich

Zahl

lt

Weniger als

Zahl

ge

Größer als oder gleich

Zahl

gt

Größer als

Beispiel:

Im folgenden Beispiel werden alle Kurse abgerufen, die das Schlüsselwort "tests" im Kursnamen enthalten:

https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests

Verwenden mehrerer Filter

Sie können die Sortier- und Filteroptionen in derselben Endpunkt-URL kombinieren, indem Sie das Zeichen „&‟ zwischen den beiden Bedingungen hinzufügen. Angenommen, Sie möchten alle Kurse abrufen, die das Schlüsselwort „test‟ im Kursnamen enthalten, für den Ally aktiviert ist, und für die das Gesamtergebnis weniger als 90 % beträgt. Die URL würde wie folgt aussehen:

https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9

Sie können auch zwei Filteroptionen verwenden. Angenommen, Sie möchten alle Kurse mit einem Gesamtergebnis zwischen 10 % und 70 % abrufen:

https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7