Extrems de l'API d'informes
Els extrems inclosos a l'API per als informes són extrems privats i no inclouen una política d'obsolescència en aquest moment. Anthology Ally pot canviar o actualitzar aquests extrems en funció del nostre full de ruta o de les versions futures.
Reviseu la documentació tècnica següent per obtenir informació sobre com configurar i personalitzar adequadament els extrems. No dubteu a consultar Com integrar l'API d'Ally amb una eina d'informes externa per obtenir orientació addicional.
Mètodes disponibles
L'API d'Ally per als informes té dos mètodes. L'apartat següent els descriu:
| Mètode | URL | Tipus de sol·licitud HTTP | Descripció |
| Global | https://[region]/api/v2/clients/[Ally Client ID]/reports/overall | Obtenir | Per defecte, aquest mètode retorna un conjunt de dades amb informació sobre el curs, WYSIWYG, i les puntuacions i tipus de fitxers inclosos en cada curs de la instància del sistema de gestió de l'aprenentatge, independentment de si Ally està habilitat o no. |
| Incidències | https://[region]/api/v2/clients/[Ally Client ID]/reports/issues | Obtenir | Per defecte, aquest mètode retorna un conjunt de dades amb informació sobre totes les incidències d'accessibilitat que succeeixen dins de cada curs inclòs en la instància del sistema de gestió de l'aprenentatge, independentment de si Ally està habilitat o no. |
Substituïu[Ally Client ID] amb el vostre ID d'Ally. Si no sabeu quin és el vostre ID, podeu crear un tiquet d'assistència per sol·licitar-lo.
Substituïu[Region] en funció de la regió on estigui allotjat l'entorn d'Ally de la vostra institució:
- Centre de dades dels EUA:prod.ally.ac
- Centre de dades canadenc:prod-ca-central-1.ally.ac
- Centre de dades europeu:prod-eu-central-1.ally.ac
- Centre de dades de Singapur:prod-ap-southeast-1.ally.ac
- Centre de dades australià:prod-ap-southeast-2.ally.ac
La informació anterior pot variar en funció del sistema de gestió de l'aprenentatge. Podeu revisar la definició de columnes a la documentació de l'informe del curs per a cada sistema de gestió de l'aprenentatge:
Resposta d'estat HTTP
L'API d'Ally inclou un camp d'estat a les metadades de la manera següent:
- Estat 200 - Correcte: La vostra sol·licitud s'ha rebut correctament i el conjunt de dades sol·licitat forma part de la resposta.
- Estat 202 - S'està processant: La vostra sol·licitud s'ha rebut correctament, però el conjunt de dades s'està preparant i encara no està disponible. Repetiu la sol·licitud al cap d'un temps (es recomana almenys un minut).
- Estat 401 - No autoritzat: L'ID de client d'Ally o el testimoni d'autorització no són correctes.
- Estat 400 - Mala sol·licitud: L'URL té un nom de paràmetre no vàlid, per exemple, una opció, operador o valor de filtratge desconeguts. Reviseu la sintaxi de l'URL. Recordeu que algunes de les opcions de filtratge i ordenació distingeixen entre majúscules i minúscules.
Documentació de mètodes
Mètode: En general
Sol·licitud HTTP:GET
https://[Region]/api/v2/clients/[Ally Client ID]/reports/overall
Substituïu[Ally Client ID] amb el vostre ID d'Ally. Si no sabeu quin és el vostre ID, podeu crear un tiquet d'assistència per sol·licitar-lo.
Substituïu[Region] en funció de la regió on estigui allotjat l'entorn d'Ally de la vostra institució:
- Centre de dades dels EUA:prod.ally.ac
- Centre de dades canadenc:prod-ca-central-1.ally.ac
- Centre de dades europeu:prod-eu-central-1.ally.ac
- Centre de dades de Singapur:prod-ap-southeast-1.ally.ac
- Centre de dades australià:prod-ap-southeast-2.ally.ac
Autorització: testimoni de portador d'OAuth
Paràmetres: Filtres opcionals o opcions d'ordenació.
Cos de la sol·licitud: Cap
Resposta:
{
"data": [
{
"application/x-quiz": 2,
“observedDeletedOn”: "",
"termName": “Tardor 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”: "Biologia bàsica",
"application/x-discussion-topic":1,
"other": 11,
"overallScore":0,6129724428830603,
"presentation":5
}
],
“metadata”: {
"filteredTotal":0,
"total":7186,
"to": 7186,
"status":"Processing",
"from":1
}
}
Mètode: Incidències
Sol·licitud HTTP:GET
https://[Region]/api/v2/clients/[Ally Client ID]/reports/overall
Substituïu [Ally Client ID] amb el vostre ID d'Ally. Si no sabeu quin és el vostre ID, podeu crear un tiquet d'assistència per sol·licitar-lo.
Substituïu[Region] en funció de la regió on estigui allotjat l'entorn d'Ally de la vostra institució:
- Centre de dades dels EUA:prod.ally.ac
- Centre de dades canadenc:prod-ca-central-1.ally.ac
- Centre de dades europeu:prod-eu-central-1.ally.ac
- Centre de dades de Singapur:prod-ap-southeast-1.ally.ac
- Centre de dades australià:prod-ap-southeast-2.ally.ac
Autorització: testimoni de portador d'OAuth
Paràmetres: filtres opcionals o opcions d'ordenació.
Cos de la sol·licitud: cap
Resposta:
{
"data": [
{
"imageDecorative2": 4,
"htmlEmptyHeading2": 0,
"imageSeizure1": 2,
“observedDeletedOn”:"",
"htmlObjectAlt2": 0,
"security1": 3,
"termName": “Tardor 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":"Biologia bàsica",
"imageContrast2": 0,
"imageDescription2": 4,
"htmlTitle3": 1,
"parsable1":2
}
],
"metadata":{
"filteredTotal":0,
"total":7186,
"to": 7186,
"status":"Processing",
"from":1
}
}
On:
- Dades: conté el conjunt de dades dels resultats.
- Metadades:
- A: registre al qual s'obtindran les dades, és “desplaçament” + “límit” o “total” si la suma supera “total”.
- De: registre a partir del qual s'iniciaran les dades, és “desplaçament” + 1.
- Total: nombre total de cursos considerats per Ally en la instància del sistema de gestió de l'aprenentatge.
Desplaçament: a partir del qual comença el registre
- La primera fila està desplaçada = 0,
- Quan desplaçament < 0, l'usuari rep l'error 400 - [Valor no vàlid (paràmetre=desplaçament, missatge=sense dades)],
- Quan (desplaçament >= total) =>; l'usuari rep l'error 400 - [Valor no vàlid (paràmetre=desplaçament, missatge=sense dades)]
Límit: quants registres es recuperen començant des del desplaçament
- Quan (límit < 1), l'usuari obté l'error 400 - [Valor no vàlid (paràmetre=límit, missatge=límit fora del límit)]
- Quan (límit > 10000) l'usuari obté l'error 400 - [Valor no vàlid (paràmetre=límit, missatge=límit fora del límit)]
- Quan (desplaçament < total i desplaçament + límit > total), us canviem el límit en segon pla i les dades es recuperaran fins a l'últim (total)
Filtres i opcions d'ordenació
Les respostes dels extrems es poden filtrar a l'URL. En aquest apartat es descriuen les opcions disponibles:
Opcions d'ordenació
Podeu definir si voleu mostrar els resultats ordenats en ordre ascendent o descendent tenint en compte un criteri. Si necessiteu afegir una opció d'ordenació, heu d'afegir el paràmetre d'ordenació tal com es descriu a continuació:
endpoint-url?sort=
On pot ser qualsevol dels següents valors de paràmetre:
| Valor del paràmetre | Descripció | Compatible a | Exemple |
| courseName | Ordenar pel nom del curs, p. ex., Química 101 (courseCode no és vàlid) | Extrems generals i d'incidències | endpoint-url?sort=courseName |
| courseId | Ordenar per l'ID del curs, p. ex., 123456 (sol ser un nombre enter) | Extrems generals i d'incidències | endpoint-url?sort=courseId |
| termId | Ordenar per l'ID del terme. P. ex. Sum | Extrems generals i d'incidències | endpoint-url?sort=termId |
| termName | Ordenar pel nom del terme. P. ex., Estiu | Extrems generals i d'incidències | endpoint-url?sort=termName |
| overallScore | Ordenar per la puntuació global d'accessibilitat de cada curs. | Només extrem general. | endpoint-url?sort=overallScore |
| filesScore | Ordenar els resultats per la puntuació de cada curs. | Només extrem general. | endpoint-url?sort=filesScore |
| wysiwygScore | Ordenar els resultats per la puntuació WYSIWYG de cada curs. | Extrem general i només disponible per a Ally per al sistema de gestió de l'aprenentatge. | endpoint-url?sort= wysiwygScore |
| webPagesScore | Ordenar els resultats per la puntuació de la pàgina web de cada domini. | Extrem general i només disponible per a Ally per a Web i WCM. | endpoint-url?sort= webPagesScore |
Els valors dels paràmetres distingeixen entre majúscules i minúscules i només es pot utilitzar una opció d'ordenació alhora.
Per defecte, els resultats s'ordenen en ordre ascendent. Si voleu establir un ordre diferent, podeu afegir el paràmetre d'ordenació:
endpoint-url?sort=&order=
On pot ser: asc o desc
Exemple:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Opcions de filtratge
Podeu utilitzar opcions de filtratge per obtenir respostes més petites o reduïdes en funció dels criteris seleccionats. Si necessiteu afegir una opció de filtratge, heu d'afegir el paràmetre de filtratge tal com es descriu a continuació:
Paràmetres de filtre (sense operador)
| Nom del paràmetre de filtre | Descripció | Compatible a |
| allyEnabled | Podeu obtenir els cursos en què Ally està actiu El valor és vertader o fals | Extrems generals i incidències |
| departamentId | Filtrar per l'ID del departament | Extrems generals i d'incidències |
| departmentName | Filtrar pel nom del departament. P. ex. Enginyeria | Extrems generals i d'incidències |
| termId | Filtrar per l'ID del terme | Extrems generals i d'incidències |
| termName | Filtrar pel nom del terme. P. ex. Estiu | Extrems generals i d'incidències |
| courseId | Filtra per l'ID o per un curs. P. ex. 123456 (sol ser un nombre enter) | Extrems generals i d'incidències |
| courseName | Filtrar pel nom d'un curs. P. ex. Química bàsica (courseCode no és vàlid) | Extrems generals i d'incidències |
endpoint-url?=
Paràmetres del filtre (amb operador)
endpoint-url?=:
On:
- : Paràmetre de filtratge per obtenir un conjunt més petit de resultats. Podeu consultar els paràmetres admesos a la taula següent.
- : Heu d'utilitzar un operador per filtrar, com igual, no igual.
- : Valor utilitzat en el filtre.
| Nom del paràmetre de filtre | Tipus de camp | Operadors admesos | Descripció | Compatible a |
| allyEnabled | Booleà | eq, ne | Podeu obtenir els cursos en què Ally està actiu El valor és vertader o fals | Extrems generals i d'incidències |
| courseName | Cadena | eq, ne, co, nc, sw | Filtrar pel nom d'un curs. P. ex. Química bàsica (courseCode no és vàlid) | Extrems generals i d'incidències |
| courseId | Cadena | eq, ne, co, nc, sw | Filtra per l'ID o per un curs. P. ex. 123456 (sol ser un nombre enter) | Extrems generals i d'incidències |
| termId | Cadena | eq, ne, co, nc, sw | Filtrar per l'ID d'un terme. | Extrems generals i d'incidències |
| termName | Cadena | eq, ne, co, nc, sw | Filtrar pel nom del terme. P. ex. Estiu | Extrems generals i d'incidències |
| overallScore | Número | eq, ne, le, lt, ge, gt | Podeu filtrar per una puntuació general. P. ex. Cursos amb una puntuació igual al 90 % | Extrem general i en totes les solucions d'Ally: Sistema de gestió de l'aprenentatge, llocs web i WCM. |
| filesScore | Número | eq, ne, le, lt, ge, gt | Podeu filtrar per la puntuació dels fitxers. P. ex. Cursos amb una puntuació d'arxius igual al 90 % | Extrem general i en totes les solucions d'Ally: Sistema de gestió de l'aprenentatge, llocs web i WCM. |
| wysiwygScore | Número | eq, ne, le, lt, ge, gt | Podeu filtrar per la puntuació WYSIWYG. P. ex. Cursos amb una puntuació WYSIWYG igual al 90 % | Extrem general i només disponible per a Ally per al sistema de gestió de l'aprenentatge. |
| webPagesScore | Número | eq, ne, le, lt, ge, gt | Podeu filtrar per la puntuació d'un domini. P. ex. Pàgines web amb una puntuació igual al 90 %. | Extrem general i només disponible per a Ally per al web o WCM. |
Els valors dels paràmetres distingeixen entre majúscules i minúscules.
Operadors admesos
La taula següent conté els operadors admesos en funció del tipus de camp:
| Tipus de camp | Operador | Descripció |
| Cadena | eq | És igual |
| Cadena | ne | No és igual |
| Cadena | co | Conté paraula clau |
| Cadena | nc | No conté paraula clau |
| Cadena | sw | Comença amb paraula clau |
| Número | eq | És igual |
| Número | ne | No és igual |
| Número | le | Inferior o igual |
| Número | lt | Menys de |
| Número | ge | Major o igual que |
| Número | gt | Superior a |
Exemple:
L'exemple següent recupera tots els cursos que contenen la paraula clau “proves” en el nom del curs:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Ús de diversos filtres
Podeu combinar les opcions d'ordenació i filtratge al mateix URL de l'extrem afegint el caràcter “&” entre les dues condicions. Per exemple, suposem que voleu recuperar tots els cursos que contenen la paraula clau “prova” al nom del curs on Ally està habilitat i que la puntuació global és inferior al 90 %. L'URL tindria aquest aspecte:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
També podeu utilitzar dues opcions de filtratge. Per exemple, suposem que heu d'obtenir tots els cursos que tenen una puntuació global entre el 10 % i el 70 %:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7
