Signaler les points de terminaison des interfaces de programmation d'application
Signaler les points de terminaison des interfaces de programmation d'application
Avertissement
Les terminaux inclus dans l'interface de programmation d'application pour les rapports sont des points de terminaison privés et ne sont pas soumis à une politique de dépréciation 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 correctement vos terminaux. 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'interface de programmation d'application Ally pour les rapports comporte deux méthodes. La section suivante les décrit :
Méthode | URL | Type de requête HTTP | Description |
Dans l'ensemble | https://[region]/api/v2/clients/[Ally Client ID]/reports/overall | Obtenez | 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. |
Enjeux | https://[region]/api/v2/clients/[Ally Client ID]/reports/issues | Obtenez | 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. |
Astuce
Remplacez [ID client Ally] par votre identifiant Ally. Si vous ne connaissez pas votre identifiant, vous pouvez créer un ticket d'assistance pour en faire la demande.
Astuce
Remplacez [Region] par la région où l'environnement Ally de votre établissement est hébergé :
Centre de données américain : prod.ally.ac
Centre de données canadien : prod-ca-central-1.ally.ac
Centre de données européen : prod-eu-central-1.ally.ac
Centre de données de Singapour : prod-ap-southeast-1.ally.ac
Centre de données australien : prod-ap-southeast-2.ally.ac
Réponse d'état HTTP
L'interface de programmation d'application Ally inclut un champ d'état dans les métadonnées comme suit :
État 200 - Réussite : votre demande a été reçue avec succès et l'ensemble de données demandé fait partie de la réponse.
État 202 - Traitement : Votre demande a été reçue avec succès mais l'ensemble de données est en cours de préparation et n'est pas encore disponible. Répétez votre demande après un certain temps (au moins une minute est recommandée).
État 401 - Non autorisé : l'ID client Ally ou le jeton d'autorisation ne sont pas corrects.
État 400 - Demande incorrecte : l'URL contient un nom de paramètre non valide, par exemple une option de filtre, un opérateur ou une valeur inconnus. Vérifiez la syntaxe de l'URL. N'oubliez pas que certaines options de filtrage et de tri font la distinction entre majuscules et minuscules.
Documentation sur les méthodes
Méthode : Globale
Requête HTTP : GET
https:// [Region]/api/v2/clients/[Ally Client ID]/reports/overall
Remplacez [ID client Ally] par votre identifiant Ally. Si vous ne connaissez pas votre identifiant, vous pouvez créer un ticket d'assistance pour en faire la demande.
Remplacez [Region] par la région où l'environnement Ally de votre établissement est hébergé :
Centre de données américain : prod.ally.ac
Centre de données canadien : prod-ca-central-1.ally.ac
Centre de données européen : prod-eu-central-1.ally.ac
Centre de données de Singapour : prod-ap-southeast-1.ally.ac
Centre de données australien : 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 : problèmes
Requête HTTP : GET
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 identifiant, vous pouvez créer un ticket d'assistance pour en faire la demande.
Remplacez [Region] par la région où l'environnement Ally de votre établissement est hébergé :
Centre de données américain : prod.ally.ac
Centre de données canadien : prod-ca-central-1.ally.ac
Centre de données européen : prod-eu-central-1.ally.ac
Centre de données de Singapour : prod-ap-southeast-1.ally.ac
Centre de données australien : 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 :
À : enregistrement vers lequel les données seront extraites, « décalage » + « limite » ou « total » si la somme dépasse « total ».
De : enregistrement à partir duquel les données vont commencer, c'est « offset » + 1.
Total : nombre total de cours pris en compte par Ally dans l'instance LMS.
Offset : à partir duquel l'enregistrement commence
La première ligne est offset = 0,
Lorsque le décalage est inférieur à 0, l'utilisateur reçoit l'erreur 400 - [ Valeur non valide (paramètre=offset, 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 : combien d'enregistrements sont récupérés à partir de l'offset
Lorsque (limite < 1), l'utilisateur obtient l'erreur 400 - [Valeur non valide (paramètre=limite, message=Limite hors limites)]
Lorsque (limite >10000), l'utilisateur reçoit l'erreur 400 - [ Valeur non valide (paramètre=limite, message=Limite hors limites) ]
Quand (< total && offset + limit >total du décalage), nous modifierons la limite en arrière-plan pour vous, et les données seront récupérées jusqu'à la fin (total)
Filtres et options de tri
Les réponses des terminaux peuvent être filtrées dans l'URL. Cette section décrit les options disponibles :
Options de tri
Vous pouvez définir si vous souhaitez afficher les résultats triés par ordre croissant ou décroissant en fonction 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 :
URL du point de terminaison ? trier=<Sort parameter value>
Où <Sort parameter value> peut être l'une des valeurs de paramètre de tri suivantes :
Valeur du paramètre | Description | Pris en charge dans | Exemple |
Nom du cours | Trier par nom de cours, par exemple Chimie 101 (courseCode n'est pas valide) | Points finaux généraux et problèmes | URL du point de terminaison ? sort=nom du cours |
Identifiant du cours | Trier par numéro de cours, par exemple 123456 (il s’agit généralement d’un nombre entier) | Points finaux généraux et problèmes | URL du point de terminaison ? sort=ID de cours |
ID de terme | Triez par identifiant de terme. Par exemple, Sum | Points finaux généraux et problèmes | URL du point de terminaison ? sort=TermiD |
Nom du terme | Trier par nom du terme. Par exemple Été | Points finaux généraux et problèmes | URL du point de terminaison ? sort=Nom du terme |
Note globale | Triez selon le score d'accessibilité global de chaque cours. | Point final global uniquement. | URL du point de terminaison ? SORT = note globale |
Score des fichiers | Triez les résultats en fonction du score du fichier de chaque cours. | Point final global uniquement. | URL du point de terminaison ? sort=FilesScore |
Score WYSIWYG | Triez les résultats en fonction du score WYSIWYG de chaque cours. | Disponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour les LMS. | URL du point de terminaison ? tri = score WYSIWYG |
Score des pages Web | Triez les résultats en fonction du score de 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. | URL du point de terminaison ? tri = score des pages Web |
Note
Les valeurs des paramètres distinguent les majuscules et minuscules 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 une autre commande, vous pouvez ajouter le paramètre de commande :
URL du point de terminaison ?<Sort parameter value>trier= &commande=<Order value>
Où la valeur <Order value> peut être : asc ou desc
Exemple :
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Options de filtrage
Vous pouvez utiliser les options de filtrage pour obtenir des réponses plus petites ou réduites en fonction des critères sélectionnés. Si vous devez ajouter une option de filtrage, vous devez ajouter le paramètre de filtrage comme décrit ci-dessous :
Paramètres du filtre (sans opérateur)
Nom du paramètre de filtre | Description | Pris en charge dans |
allyEnabled | Permet d'obtenir les cours pour lesquels Ally est actif La valeur est vraie ou fausse | Points finaux généraux et problèmes |
ID du département | Filtrer par numéro de département | Points finaux généraux et problèmes |
Nom du département | Filtrer par le nom du département. Par exemple, Ingénierie | Points finaux généraux et problèmes |
ID de terme | Filtrer par ID du terme | Points finaux généraux et problèmes |
Nom du terme | Permet de filtrer en fonction du nom de la période. « Été », par exemple | Points finaux généraux et problèmes |
Identifiant du cours | Filtrer en fonction de l'ID ou d'un cours. Par exemple 123456 (il s’agit généralement d’un nombre entier) | Points finaux généraux et problèmes |
Nom du cours | Filtrez par nom de cours. Par exemple, Chimie 101 (courseCode n'est pas valide) | Points finaux généraux et problèmes |
URL du point de terminaison ?<Filter Parameter>=<value>
Paramètres du filtre (avec opérateur)
URL du point de terminaison ?<Filter Parameter>= <Operator>:<value>
Où :
<Filter Parameter> : 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.
<Operator> : vous devez utiliser un opérateur pour filtrer, par exemple « equal » (égal), « not equal » (pas égal).
<value> : valeur utilisée dans le filtre.
Nom du paramètre de filtre | Type de champ | Opérateurs pris en charge | Description | Pris en charge dans |
allyEnabled | Booléen | éq, ne | Permet d'obtenir les cours pour lesquels Ally est actif. La valeur est vraie ou fausse. | Points finaux généraux et problèmes |
Nom du cours | Chaîne | eq, ne, co, nc, sw | Filtrez par nom de cours. Par exemple, Chimie 101 (courseCode n'est pas valide) | Points finaux généraux et problèmes |
Identifiant du cours | Chaîne | eq, ne, co, nc, sw | Filtrez en fonction de l'ID ou d'un cours. Par exemple 123456 (il s’agit généralement d’un nombre entier) | Points finaux généraux et problèmes |
ID de terme | Chaîne | eq, ne, co, nc, sw | Filtrer par ID de la période de cours. | Points finaux généraux et problèmes |
Nom du terme | Chaîne | eq, ne, co, nc, sw | Permet de filtrer en fonction du nom de la période. « Été », par exemple | Points finaux généraux et problèmes |
Note globale | Numéro | eq, ne, le, lt, ge, gt | Vous pouvez filtrer en fonction d'un score global. Par exemple, les cours avec un score égal à 90 % | Endpoint global et intégré à toutes les solutions Ally : LMS, sites Web et WCM. |
Score des fichiers | Numéro | eq, ne, le, lt, ge, gt | Vous pouvez filtrer en fonction du score des fichiers. Par exemple, les cours dont le score des fichiers est égal à 90 % | Endpoint global et intégré à toutes les solutions Ally : LMS, sites Web et WCM. |
Score WYSIWYG | Numéro | eq, ne, le, lt, ge, gt | Vous pouvez filtrer en fonction du score WYSIWYG. Par exemple, les cours avec un score WYSIWYG égal à 90 % | Disponible uniquement pour les points de terminaison de la méthode Overall (globale) et pour Ally pour les LMS. |
Score des pages Web | Numéro | eq, ne, le, lt, ge, gt | Vous pouvez filtrer en fonction du score d'un domaine. Par exemple, les pages Web avec un score égal à 90 %. | Point de terminaison global et uniquement disponible pour Ally for Web ou WCM. |
Note
Les valeurs des paramètres distinguent les majuscules et minuscules.
Opérateurs pris en charge
Le tableau suivant contient les opérateurs pris en charge en fonction du type de champ :
Type de champ | Opérateur | Description |
Chaîne | eq | Est égal |
Chaîne | ne | N'est pas égal |
Chaîne | co | Contient un mot clé |
Chaîne | Caroline du Nord | Ne contient pas de mot clé |
Chaîne | so | Commence par un mot clé |
Numéro | eq | Est égal |
Numéro | ne | N'est pas égal |
Numéro | le | Inférieur ou égal |
Numéro | lt | Moins de |
Numéro | gm | Supérieur ou égal |
Numéro | gt | Plus grand que |
Exemple :
L'exemple suivant extrait tous les cours dont le nom contient le mot clé « tests » :
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. Par exemple, supposons que vous deviez obtenir tous les cours dont la note globale est comprise entre 10 % et 70 % :
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7