Les points de terminaison inclus dans l'API pour la création de rapports sont des points de terminaison privés et ne font pas l'objet d'une politique d'obsolescence pour le moment. Anthology Ally peut modifier ou mettre à jour ces points de terminaison en fonction de sa feuille de route ou des versions futures.

Consultez la documentation technique suivante pour savoir comment configurer et personnaliser vos points de terminaison de manière appropriée. Pour obtenir des conseils supplémentaires, n'hésitez pas à consulter la section Comment intégrer l'API Ally à un outil de création de rapports externe.

Méthodes disponibles

L'Ally API de création de rapports comporte deux méthodes, à savoir :

Méthode :URLType de requête HTTPDescription
Overall (globale)https://[region]/api/v2/clients/[Ally Client ID]/reports/overallObtenirPar défaut, cette méthode renvoie un ensemble de données contenant des informations sur le cours, le code WYSIWYG, les résultats des fichiers et les types de fichiers inclus dans chaque cours à partir de l'instance LMS, qu'Ally soit activé ou non.
Issues (problèmes)https://[region]/api/v2/clients/[Ally Client ID]/reports/issuesObtenirPar défaut, cette méthode renvoie un ensemble de données contenant des informations sur tous les problèmes d'accessibilité recensés dans chaque cours à partir de l'instance LMS, qu'Ally soit activé ou non.

Remplacez [Ally Client ID] par votre code client Ally. Si vous ne connaissez pas votre code client, vous pouvez créer un ticket d'assistance pour le demander.

Remplacez [Region] par la région où l'environnement Ally de votre établissement est hébergé.

Les informations ci-dessus peuvent varier en fonction du LMS. Vous pouvez consulter la définition de colonne dans la documentation du rapport de cours pour chaque LMS :

Réponse d'état HTTP

L'API Ally inclut un champ d'état dans les métadonnées, comme indiqué ci-dessous.

  • État 200 - Réussi : votre demande a bien été reçue et la réponse comprend l'ensemble de données demandé.
  • État 202 - Traitement : votre demande a bien été reçue, mais l'ensemble de données est en cours de préparation et n'est pas encore disponible. Renouvelez votre demande dans un moment (nous recommandons au moins une minute).
  • État 401 - Non autorisé : le code client Ally ou le jeton d'autorisation est incorrect.
  • État 400 - Demande incorrecte : l'URL possède un nom de paramètre non valide, comme une option, un opérateur ou une valeur de filtrage inconnu. Vérifiez la syntaxe de l'URL. N'oubliez pas que certaines options de filtrage et de tri sont sensibles à la casse.

Documentation des méthodes

Méthode : Overall (globale)

Requête HTTP : OBTENIR
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall

Remplacez [Ally Client ID] par votre code client Ally. Si vous ne connaissez pas votre code client, vous pouvez créer un ticket d'assistance pour le demander.

Remplacez [Region] par la région où l'environnement Ally de votre établissement est hébergé.

Autorisation : jeton porteur d'OAuth

Paramètres : options de filtrage ou de tri facultatives

Corps de la demande : aucun

Réponse :

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

Méthode : Issues (problèmes)

Requête HTTP : OBTENIR
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall

Remplacez [Ally Client ID] par votre code client Ally. Si vous ne connaissez pas votre code client, vous pouvez créer un ticket d'assistance pour le demander.

Remplacez [Region] par la région où l'environnement Ally de votre établissement est hébergé.

Autorisation : jeton porteur d'OAuth

Paramètres : options de filtrage ou de tri facultatives

Corps de la demande : aucun

Réponse :

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

Où :

  • Données : contient l'ensemble de données des résultats.
  • Métadonnées :
    • To (à) : enregistrement vers lequel les données seront récupérées, c'est-à-dire « offset (décalage) » + « limit (limite) » ou « total » si la somme dépasse « total ».
    • From (de) : enregistrement à partir duquel les données commenceront, c'est-à-dire « offset (décalage) » + 1.
    • Total : nombre total de cours pris en compte par Ally dans l'instance LMS.

Offset (Décalage) à partir duquel l'enregistrement commence

  • Le décalage de la première ligne est de 0.
  • Lorsque le décalage < 0, alors l'utilisateur reçoit l'erreur 400 : [Invalid value (parameter=offset, message=No such data)],  ([Valeur non valide (paramètre=décalage, message=aucune donnée de ce type)])
  • Lorsque (décalage >= total) => alors l'utilisateur reçoit l'erreur 400 : [Invalid value (parameter=offset, message=No such data)] ([Valeur non valide (paramètre=décalage, message=aucune donnée de ce type)])

Limite : nombre d'enregistrements récupérés à partir du décalage

  • Lorsque (limite < 1), l'utilisateur obtient l'erreur 400 - [Valeur non valide (paramètre=limite, message=Limite hors limites)]
  • Lorsque (limit > 10 000), l'utilisateur obtient l'erreur 400 - [Valeur non valide (paramètre=limite, message=Limite hors limites)]
  • Lorsque (offset < total = offset + limit > total), nous modifions la limite en arrière-plan pour vous, et les données seront récupérées jusqu'au dernier enregistrement (total)

Filtres et options de tri

Les réponses de points de terminaison peuvent être filtrées dans l'URL. Le tableau suivant décrit les options disponibles.

Options de tri

Vous pouvez définir si vous souhaitez afficher les résultats classés par ordre croissant ou décroissant en tenant compte d'un critère. Si vous devez ajouter une option de tri, vous devez ajouter le paramètre de tri comme décrit ci-dessous :

endpoint-url?sort=

peut être l'une des valeurs de paramètre suivantes :

Valeur du paramètreDescriptionPris en charge parExemple
courseNamePermet un tri par nom de cours, par exemple « Introduction à la chimie » (courseCode n'est pas valide)
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)endpoint-url?sort=courseName
courseIdPermet un tri par ID de cours, par exemple 123456
(il s'agit généralement d'un nombre entier)
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)endpoint-url?sort=courseId
termIdPermet un tri par code de période, par exemple « Été »Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)endpoint-url?sort=termId
termNamePermet un tri par nom de période, par exemple « Été »Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)endpoint-url?sort=termName
overallScorePermet un tri en fonction du résultat d'accessibilité global de chaque coursPoint de terminaison de la méthode Overall (globale) uniquementendpoint-url?sort=overallScore
filesScorePermet un tri des résultats en fonction du résultat du fichier de chaque coursPoint de terminaison de la méthode Overall (globale) uniquementendpoint-url?sort=filesScore
wysiwygScorePermet un tri des résultats en fonction du résultat WYSIWYG de chaque coursDisponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour les LMSendpoint-url?sort= wysiwygScore
webPagesScorePermet un tri des résultats en fonction du résultat de la page Web de chaque domaineDisponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour le Web et WCMendpoint-url?sort= webPagesScore

Les valeurs des paramètres sont sensibles à la casse et une seule option de tri peut être utilisée à la fois.

 

Par défaut, les résultats sont triés par ordre croissant. Si vous souhaitez définir un ordre différent, vous pouvez ajouter le paramètre « order » :

endpoint-url?sort=&order=

peut être l'une des valeurs de commande suivante : asc ou desc

Exemple :

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

Options de filtrage

Vous pouvez utiliser des options de filtrage pour obtenir des réponses réduites en fonction des critères sélectionnés. Si vous avez besoin d'une telle option, vous devez ajouter le paramètre de filtrage comme décrit ci-dessous :

Paramètres de filtrage (sans opérateur)

Nom du paramètre de filtrageDescriptionPris en charge par
allyEnabledPermet d'obtenir les cours pour lesquels Ally est actif.
La valeur retournée est true (vrai) ou false (faux).
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
departmentIdPermet de filtrer par code de départementPoints de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
departmentNamePermet de filtrer en fonction du nom du département, par exemple « Ingénierie »Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
termIdPermet de filtrer par code de périodePoints de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
termNamePermet de filtrer en fonction du nom de la période, par exemple « Été »Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
courseIdPermet de filtrer par code ou par cours, par exemple 123456
(il s'agit généralement d'un nombre entier)
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
courseNamePermet de filtrer par nom de cours, par exemple « Introduction à la chimie »
(courseCode n'est pas valide)
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)

endpoint-url?=

Paramètres de filtrage (avec opérateur)

endpoint-url?=:

Où :

  •  : paramètre de filtrage pour obtenir un ensemble de résultats plus petit. Vous pouvez consulter les paramètres pris en charge dans le tableau ci-dessous.
  •  : vous devez utiliser un opérateur pour filtrer, par exemple « equal » (égal), « not equal » (pas égal).
  •  : valeur utilisée dans le filtre.
Nom du paramètre de filtrageTypes de champsOpérateurs pris en chargeDescriptionPris en charge par
allyEnabledBooléeneq, nePermet d'obtenir les cours pour lesquels Ally est actif.
La valeur retournée est true (vrai) ou false (faux).
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
courseNameChaîneeq, ne, co, nc, swPermet de filtrer par nom de cours, par exemple « Introduction à la chimie »
(courseCode n'est pas valide)
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
courseIdChaîneeq, ne, co, nc, swPermet de filtrer par code ou par cours, par exemple 123456
(il s'agit généralement d'un nombre entier)
Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
termIdChaîneeq, ne, co, nc, swPermet de filtrer par code de périodePoints de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
termNameChaîneeq, ne, co, nc, swPermet de filtrer en fonction du nom de la période, par exemple « Été »Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes)
overallScoreNuméroeq, ne, le, lt, ge, gtPermet de filtrer par résultat global. Les cours avec un résultat égal à 90 %, par exemplePoint de terminaison pour la méthode Overall (globale) et dans toutes les solutions Ally : LMS, sites Web et WCM.
filesScoreNuméroeq, ne, le, lt, ge, gtPermet de filtrer en fonction du résultat des fichiers, par exemple les cours avec un résultat de fichiers égal à 90 %Point de terminaison pour la méthode Overall (globale) et dans toutes les solutions Ally : LMS, sites Web et WCM.
wysiwygScoreNuméroeq, ne, le, lt, ge, gtPermet de filtrer par résultat WYSIWYG, par exemple les cours avec un résultat WYSIWYG égal à 90 %Disponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour les LMS
webPagesScoreNuméroeq, ne, le, lt, ge, gtPermet de filtrer par résultat de domaine, par exemple les pages Web avec un résultat égal à 90 %Point de terminaison pour la méthode Overall (globale), uniquement pour Ally pour Web ou WCM

Les valeurs des paramètres sont sensibles à la casse.

Opérateurs pris en charge

Le tableau suivant contient les opérateurs pris en charge en fonction du type de champ :

Types de champsOpérateurDescription
ChaîneeqEst égal
ChaîneneN'est pas égal
ChaînecoContient un mot-clé
ChaînencNe contient pas de mot-clé
ChaîneswCommence par le mot-clé
NuméroeqEst égal
NuméroneN'est pas égal
NuméroleInférieur ou égal à
NuméroltInférieur à
NumérogeSupérieur ou égal à
NumérogtSupérieur à

Exemple :

L'exemple suivant récupère tous les cours qui contiennent le mot-clé « tests » dans le nom du cours.

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

Utilisation de plusieurs filtres

Vous pouvez combiner les options de tri et de filtrage dans la même URL de point de terminaison en ajoutant le caractère « & » entre les deux conditions. Par exemple, supposons que vous souhaitiez récupérer tous les cours qui contiennent le mot-clé « test » dans leur nom du cours pour lesquels Ally est activé et dont le résultat global est inférieur à 90 %. L'URL ressemblerait à ceci :

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

Vous pouvez également utiliser deux options de filtrage. Supposons par exemple que vous souhaitiez obtenir tous les cours qui ont un résultat global compris entre 10 % et 70 % :

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