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 : | URL | Type de requête HTTP | Description |
| Overall (globale) | https://[region]/api/v2/clients/[Ally Client ID]/reports/overall | Obtenir | Par 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/issues | Obtenir | Par 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é.
- Centre de données pour les États-Unis : prod.ally.ac
- Centre de données pour le Canada : prod-ca-central-1.ally.ac
- Centre de données pour l'Europe : prod-eu-central-1.ally.ac
- Centre de données pour Singapour : prod-ap-southeast-1.ally.ac
- Centre de données pour l'Australie : prod-ap-southeast-2.ally.ac
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é.
- Centre de données pour les États-Unis : prod.ally.ac
- Centre de données pour le Canada : prod-ca-central-1.ally.ac
- Centre de données pour l'Europe : prod-eu-central-1.ally.ac
- Centre de données pour Singapour : prod-ap-southeast-1.ally.ac
- Centre de données pour l'Australie : prod-ap-southeast-2.ally.ac
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é.
- Centre de données pour les États-Unis : prod.ally.ac
- Centre de données pour le Canada : prod-ca-central-1.ally.ac
- Centre de données pour l'Europe : prod-eu-central-1.ally.ac
- Centre de données pour Singapour : prod-ap-southeast-1.ally.ac
- Centre de données pour l'Australie : prod-ap-southeast-2.ally.ac
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=
Où peut être l'une des valeurs de paramètre suivantes :
| Valeur du paramètre | Description | Pris en charge par | Exemple |
| courseName | Permet 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 |
| courseId | Permet 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 |
| termId | Permet 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 |
| termName | Permet 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 |
| overallScore | Permet un tri en fonction du résultat d'accessibilité global de chaque cours | Point de terminaison de la méthode Overall (globale) uniquement | endpoint-url?sort=overallScore |
| filesScore | Permet un tri des résultats en fonction du résultat du fichier de chaque cours | Point de terminaison de la méthode Overall (globale) uniquement | endpoint-url?sort=filesScore |
| wysiwygScore | Permet un tri des résultats en fonction du résultat WYSIWYG de chaque cours | Disponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour les LMS | endpoint-url?sort= wysiwygScore |
| webPagesScore | Permet un tri des résultats en fonction du résultat de la page Web de chaque domaine | Disponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour le Web et WCM | endpoint-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=
Où 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 filtrage | Description | Pris en charge par |
| allyEnabled | Permet 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) |
| departmentId | Permet de filtrer par code de département | Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes) |
| departmentName | Permet 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) |
| termId | Permet de filtrer par code de période | Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes) |
| termName | Permet 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) |
| courseId | Permet 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) |
| courseName | Permet 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 filtrage | Types de champs | Opérateurs pris en charge | Description | Pris en charge par |
| allyEnabled | Booléen | eq, ne | Permet 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) |
| courseName | Chaîne | eq, ne, co, nc, sw | Permet 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) |
| courseId | Chaîne | eq, ne, co, nc, sw | Permet 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) |
| termId | Chaîne | eq, ne, co, nc, sw | Permet de filtrer par code de période | Points de terminaison pour les méthodes Overall (globale) et Issues (problèmes) |
| termName | Chaîne | eq, ne, co, nc, sw | Permet 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) |
| overallScore | Numéro | eq, ne, le, lt, ge, gt | Permet de filtrer par résultat global. Les cours avec un résultat égal à 90 %, par exemple | Point de terminaison pour la méthode Overall (globale) et dans toutes les solutions Ally : LMS, sites Web et WCM. |
| filesScore | Numéro | eq, ne, le, lt, ge, gt | Permet 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. |
| wysiwygScore | Numéro | eq, ne, le, lt, ge, gt | Permet 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 |
| webPagesScore | Numéro | eq, ne, le, lt, ge, gt | Permet 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 champs | Opérateur | Description |
| Chaîne | eq | Est égal |
| Chaîne | ne | N'est pas égal |
| Chaîne | co | Contient un mot-clé |
| Chaîne | nc | Ne contient pas de mot-clé |
| Chaîne | sw | Commence par le mot-clé |
| Numéro | eq | Est égal |
| Numéro | ne | N'est pas égal |
| Numéro | le | Inférieur ou égal à |
| Numéro | lt | Inférieur à |
| Numéro | ge | Supérieur ou égal à |
| Numéro | gt | Supé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
