Reporting API Endpoints

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.

Verfügbare Methoden

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

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] durch die Region, in der die Ally-Umgebung Ihrer Institution gehostet wird:

• US-Rechenzentrum: prod.ally.ac
• Kanadisches Rechenzentrum: prod-ca-central-1.ally.ac
• Europäisches Rechenzentrum: prod-eu-central-1.ally.ac
• Rechenzentrum in Singapur: prod-ap-southeast-1.ally.ac
• Australisches Rechenzentrum: prod-ap-southeast-2.ally.ac

Die oben genannten Informationen können je nach LMS variieren. Sie können die Spaltendefinition in der Kursberichtsdokumentation für jedes LMS überprüfen:

• Blackboard Learn
• Moodle
• D2L Brightspace
• Instructure Canvas

HTTP-Statusantwort

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

• Status 200 – Erfolgreich: Ihre Anfrage ist eingegangen, und das angeforderte Dataset ist Teil der Antwort.
• Status 202 – Verarbeitung: Ihre Anfrage ist eingegangen, aber das Dataset wird derzeit vorbereitet 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 ist nicht korrekt.
• Status 400 – Ungültige Anforderung: Die URL hat einen ungültigen Parameternamen, z. B. eine unbekannte Filteroption, einen unbekannten Operator oder einen unbekannten Wert. Überprüfen Sie die Syntax der URL. Denken Sie daran, dass bei einigen Filter- und Sortieroptionen zwischen Groß- und Kleinschreibung unterschieden wird.

Dokumentation der Methoden

Methode: Overall

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] durch die Region, in der die Ally-Umgebung Ihrer Institution gehostet wird:

• US-Rechenzentrum: prod.ally.ac
• Kanadisches Rechenzentrum: prod-ca-central-1.ally.ac
• Europäisches Rechenzentrum: prod-eu-central-1.ally.ac
• Rechenzentrum in Singapur: prod-ap-southeast-1.ally.ac
• Australisches Rechenzentrum: prod-ap-southeast-2.ally.ac

Autorisierung: OAuth-Bearer-Token

Parameter: optionale Filter oder Sortieroptionen

Anforderungstext: keiner

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: Issues 

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] durch die Region, in der die Ally-Umgebung Ihrer Institution gehostet wird:

• US-Rechenzentrum: prod.ally.ac
• Kanadisches Rechenzentrum: prod-ca-central-1.ally.ac
• Europäisches Rechenzentrum: prod-eu-central-1.ally.ac
• Rechenzentrum in Singapur: prod-ap-southeast-1.ally.ac
• Australisches Rechenzentrum: prod-ap-southeast-2.ally.ac

Autorisierung: OAuth-Bearer-Token

Parameter: optionale Filter oder Sortieroptionen

Anforderungstext: keiner

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

Ort: 

• Data: Enthält das Dataset der Ergebnisse.
• Metadata:
  • To: Datensatz, bis zu dem Daten abgerufen werden. Dabei gilt „Offset“ + „Limit“ oder „Total“, wenn die Summe „Total“ überschreitet.
  • From: Datensatz, ab dem die Daten beginnen. Dabei gilt „Offset“ + 1.
  • Total: Gesamtanzahl der Kurse, die von Ally in der LMS-Instanz berücksichtigt wurden.

Offset – ab welchem Datensatz begonnen wird

• Erste Zeile ist Offset = 0,
• Bei Offset < 0 erhält der Benutzer den Fehler 400: [Ungültiger Wert (Parameter=Offset, Meldung=Keine solchen Daten)].
• Bei (Offset >= Total) => erhält der Benutzer den Fehler 400: [Ungültiger Wert (Parameter = Offset, Meldung = Keine solchen Daten)].

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)]
• Bei (Limit > 10000) erhält der Benutzer den Fehler 400: [Ungültiger Wert (Parameter = Limit, Meldung = Limit außerhalb des Grenzwerts)].
• Bei (Offset < Total & Offset + Limit > Total) ändern wir das Limit im Hintergrund für Sie, und die Daten werden bis zum letzten (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=<Sortierparameterwert>

Dabei kann <Sortierparameterwert> einer der folgenden Parameterwerte sein:

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=<Sortierparameterwert>&order=<Reihenfolge>

Dabei kann <Reihenfolge> Folgendes sein: asc oder desc

Beispiel:

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

Filteroptionen

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

Filterparameter (ohne Operator)

endpoint-url?<Filterparameter>=<Wert>

Filterparameter (mit Operator)

endpoint-url?<Filterparameter>=<Operator>:<Wert>

Ort: 

• <Filterparameter>: Filterparameter, um eine kleinere Anzahl von Ergebnissen zu erhalten. Die unterstützten Parameter sind in der folgenden Tabelle aufgeführt.
• <Operator>: Sie müssen zum Filtern einen Operator verwenden, z. B. „gleich“ oder „ungleich“.
• <Wert>: Im Filter verwendeter Wert.

Bei Parameterwerten wird zwischen Groß- und Kleinschreibung unterschieden.

Unterstützte Operatoren

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

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