Extremos de la API de generación de informes
Extremos de la API de generación de informes
Aviso
Los extremos incluidos en la API para la generación de informes son privados y no tienen política de desuso actualmente. Anthology Ally puede cambiar o actualizar estos extremos en función de nuestra hoja de ruta o de versiones futuras.
Consulte la siguiente documentación técnica para obtener más información sobre cómo configurar y personalizar los extremos de manera adecuada. No dude en comprobar cómo integrar la API de Ally con la herramienta externa de generación de informes para obtener orientación adicional.
Métodos disponibles
La API de Ally de generación de informes tiene dos métodos. La siguiente sección los describe así:
Método | URL | Tipo de solicitud HTTP | Descripción |
General | https://[región]/api/v2/clients/[ID de cliente de Ally]/reports/overall | Obtener | De forma predeterminada, este método devuelve un conjunto de datos con información sobre el curso, el contenido WYSIWYG, las puntuaciones de los archivos y los tipos de archivos incluidos en cada curso desde la instancia LMS, independientemente de si Ally está habilitado o no. |
Problemas | https://[región]/api/v2/clients/[ID de cliente de Ally]/reports/issues | Obtener | De forma predeterminada, este método devuelve un conjunto de datos con información relacionada con los problemas de accesibilidad de todos los cursos incluidos en la instancia del LMS, independientemente de que Ally esté habilitado o no. |
Sugerencia
Reemplace [ID de cliente de Ally] por su ID de Ally. Si desconoce su ID, puede crear un boleto de soporte técnico para solicitarlo.
Sugerencia
Reemplace [Región] según la región en la que se aloje el entorno de Ally de su institución:
Centro de datos estadounidense: prod.ally.ac
Centro de datos canadiense: prod-ca-central-1.ally.ac
Centro de datos europeo: prod-eu-central-1.ally.ac
Centro de datos de Singapur: prod-ap-southeast-1.ally.ac
Centro de datos australiano: prod-ap-southeast-2.ally.ac
Respuesta de estado HTTP
La API de Ally incluye un campo de estado en los metadatos que puede mostrar lo siguiente:
Estado 200 - Exitoso: La solicitud se recibió correctamente y el conjunto de datos solicitado forma parte de la respuesta.
Estado 202 - Procesamiento: Su solicitud fue recibida con éxito, pero el conjunto de datos está en preparación y aún no está disponible. Espere un momento antes de repetir la solicitud (se recomienda que sea al menos un minuto).
Estado 401 - No autorizado: El ID del cliente de Ally o el token de autorización no son correctos.
Estado 400 - Solicitud incorrecta: La URL tiene un nombre de parámetro inválido, por ejemplo, una opción, operador o valor de filtro desconocidos. Revise la sintaxis de la URL. Recuerda que algunas de las opciones de filtro y ordenación son sensibles a mayúsculas y mayúsculas.
Documentación de métodos
Método: En general
Solicitud HTTP: GET
https:// [Región]/api/v2/clients/[ID de cliente de Ally]/reports/overall
Reemplace [ID de cliente de Ally] por su ID de Ally. Si desconoce su ID, puede crear un boleto de soporte técnico para solicitarlo.
Reemplace [Región] según la región en la que se aloje el entorno de Ally de su institución:
Centro de datos estadounidense: prod.ally.ac
Centro de datos canadiense: prod-ca-central-1.ally.ac
Centro de datos europeo: prod-eu-central-1.ally.ac
Centro de datos de Singapur: prod-ap-southeast-1.ally.ac
Centro de datos australiano: prod-ap-southeast-2.ally.ac
Autorización: token portador de OAuth.
Parámetros: Filtros opcionales u opciones de clasificación.
Cuerpo de la solicitud: Ninguno
Respuesta:
{
"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étodo: Problemas
Solicitud HTTP: GET
https:// [Región]/api/v2/clients/[ID de cliente de Ally]/reports/overall
Reemplace [ID de cliente de Ally] por su ID de Ally. Si desconoce su ID, puede crear un boleto de soporte técnico para solicitarlo.
Reemplace [Región] según la región en la que se aloje el entorno de Ally de su institución:
Centro de datos estadounidense: prod.ally.ac
Centro de datos canadiense: prod-ca-central-1.ally.ac
Centro de datos europeo: prod-eu-central-1.ally.ac
Centro de datos de Singapur: prod-ap-southeast-1.ally.ac
Centro de datos australiano: prod-ap-southeast-2.ally.ac
Authorization: token portador OAuth
Parámetros: Filtros opcionales u opciones de clasificación.
Cuerpo de la solicitud: Ninguno
Respuesta:
{
"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
}
} Donde:
Data: contiene el conjunto de datos de los resultados.
Metadatos:
Para: registrar a qué datos se obtendrán los datos, es "desplazamiento" + "límite" o "total" si la suma supera el "total".
From: registro desde el que comenzarán los datos, es "desplazamiento" + 1.
Total: número total de cursos considerados por Ally en la instancia del LMS.
Desplazamiento - desde dónde comienza el disco
La primera fila está desplazada = 0,
Cuando está desplazado < 0, el usuario obtiene el error 400 [Valor no válido (parámetro = desplazado, mensaje = No hay datos)],
Cuando (desplazamiento >= total) = > entonces el usuario recibe el error 400 - [Valor inválido (parámetro=desplazamiento, mensaje=No hay tales datos) ]
Límite: cuántos registros se recuperan comenzando desde el offset
Cuando (límite < 1), el usuario obtiene el error 400 [Valor no válido (parámetro = límite, mensaje = Fuera de los límites)]
Cuando (límite > 10000) el usuario recibe el error 400 - [Valor inválido (parámetro=límite, mensaje=Límite fuera de límites)]
Cuando (total de desplazamiento < total && offset + limit > ), entonces cambiamos el límite en segundo plano para ti, y los datos se recuperarán hasta el final (total)
Filtros y opciones de ordenación
Las respuestas del extremo se pueden filtrar en la URL. En esta tabla se describen las opciones disponibles:
Opciones de ordenación
Puede definir si desea mostrar los resultados ordenados de forma ascendente o descendente utilizando un criterio. Si necesita una opción de orden adicional, debe agregar el parámetro de orden como se describe a continuación:
endpoint-url?sort=<Sort parameter value>
Donde <valor del parámetro Orden> puede ser cualquiera de los siguientes valores de parámetro:
Valor del parámetro | Descripción | Apoyado en | Ejemplo |
courseName | Ordena por nombre de asignatura, por ejemplo, Química 101 (courseCode no es válido) | Extremos generales y de problemas | endpoint-url?sort=courseName |
courseId | Ordena por ID de curso, por ejemplo, 123456 (normalmente es un número entero) | Extremos generales y de problemas | endpoint-url?sort=courseId |
termId | Ordenar por ID del período. Por ejemplo, Sum | Extremos generales y de problemas | endpoint-url?sort=termId |
termName | Ordena por término Nombre. por ejemplo, verano | Extremos generales y de problemas | endpoint-url?sort=termName |
Puntuación general | Ordenar por la puntuación general de accesibilidad de cada curso. | Solo en el extremo general. | endpoint-url?sort=overallScore |
filesScore | Ordenar los resultados por la puntuación del archivo de cada curso. | Solo en el extremo general. | endpoint-url?sort=filesScore |
wysiwygScore | Ordenar los resultados por la puntuación WYSIWYG de cada curso. | Extremo general y solo disponible para Ally de LMS. | endpoint-url?sort= wysiwygScore |
webPagesScore | Ordenar los resultados por la puntuación de la página web de cada dominio. | Extremo general solo disponible para Ally para la Web y WCM. | endpoint-url?sort= webPagesScore |
Nota
Los valores de los parámetros distinguen entre mayúsculas y minúsculas, y solo se puede utilizar una opción de orden a la vez.
Los resultados se ordenan de forma ascendente de manera predeterminada. Si desea establecer un orden diferente, puede agregar el parámetro orden:
endpoint-url?sort=<Sort parameter="" value="">&order=<Order value></Sort>
Donde <valor de orden> puede ser: asc o desc
Ejemplo:
https://prod.ally.ac/api/v2/clients/0/issues?sort=courseName&order=desc
Opciones de filtrado
Puede usar las opciones de filtrado para obtener respuestas más cortas o reducidas según los criterios seleccionados. Si necesitas añadir una opción de filtrado, debes añadir el parámetro de filtrado como se describe a continuación:
Parámetros de filtro (sin operador)
Nombre del parámetro del filtro | Descripción | Apoyado en |
allyEnabled | Puede obtener los cursos en los que Ally está activo El valor es verdadero o falso | Extremos generales y de problemas |
departamento Id | Filtrar por ID del departamento | Extremos generales y de problemas |
Nombre del departamento | Filtra por el nombre del departamento. por ejemplo, Ingeniería | Extremos generales y de problemas |
termId | Filtrar por ID del período | Extremos generales y de problemas |
termName | Filtra por el nombre del término. por ejemplo, verano | Extremos generales y de problemas |
courseId | Filtra por el ID o por un curso. por ejemplo, 123456 (normalmente es un número entero) | Extremos generales y de problemas |
courseName | Filtrar por el nombre de un curso. Por ejemplo, Química 101 (courseCode no es válido) | Extremos generales y de problemas |
¿endpoint-url? <Filter parameter="">=<value></Filter>
Parámetros de filtro (con operador)
¿endpoint-url? <Filter parameter="">=<Operator>:<value></Operator></Filter>
Donde:
<Parámetro de filtro>: Parámetro de filtrado para obtener un conjunto más reducido de resultados. Puede consultar los parámetros compatibles en la siguiente tabla.
<Operador>: Debes usar un operador para filtrar, como igual, no igual.
<valor>: Valor usado en el filtro.
Nombre del parámetro del filtro | Tipo de campo | Operadores soportados | Descripción | Apoyado en |
allyEnabled | Booleano | eq, ne | Puede obtener los cursos en los que Ally está activado. El valor es verdadero o falso. | Extremos generales y de problemas |
courseName | Cadena | EQ, NE, CO, NC, SW | Filtrar por el nombre de un curso. Por ejemplo, Química 101 (courseCode no es válido) | Extremos generales y de problemas |
courseId | Cadena | EQ, NE, CO, NC, SW | Filtrar por ID o curso. Por ejemplo, 123456 (normalmente es un número entero) | Extremos generales y de problemas |
termId | Cadena | EQ, NE, CO, NC, SW | Filtre por ID del período. | Extremos generales y de problemas |
termName | Cadena | EQ, NE, CO, NC, SW | Filtra por el nombre del término. por ejemplo, verano | Extremos generales y de problemas |
Puntuación general | Número | EQ, NE, LE, Lt, Ge, GT | Puede filtrar por puntuación general; por ejemplo: cursos con una puntuación igual a 90 % | Endpoint general y en todas las soluciones de Ally: LMS, sitios web y WCM. |
filesScore | Número | EQ, NE, LE, Lt, Ge, GT | Puede filtrar por la puntuación de los archivos; por ejemplo: cursos con una puntuación de archivos igual a 90 % | Endpoint general y en todas las soluciones de Ally: LMS, sitios web y WCM. |
wysiwygScore | Número | EQ, NE, LE, Lt, Ge, GT | Puede filtrar por la puntuación WYSIWYG; por ejemplo: cursos con una puntuación WYSIWYG igual a 90 % | Extremo general y solo disponible para Ally de LMS. |
webPagesScore | Número | EQ, NE, LE, Lt, Ge, GT | Puede filtrar por la puntuación de un dominio; por ejemplo: páginas web con una puntuación igual a 90 %. | Extremo general solo disponible para Ally para la Web o WCM. |
Nota
Los valores de los parámetros distinguen mayúsculas y minúsculas.
Operadores soportados
En la siguiente tabla se incluyen los operadores compatibles en función del tipo de campo:
Tipo de campo | Operador | Descripción |
Cadena | eq | Es igual |
Cadena | ne | No es igual |
Cadena | co | Contiene la palabra clave |
Cadena | nc | No contiene palabra clave |
Cadena | sw | Empieza con la palabra clave |
Número | eq | Es igual |
Número | ne | No es igual |
Número | Ie | Menor o igual |
Número | lt | Menos que |
Número | ge | Mayor o igual |
Número | gt | Mayor que |
Ejemplo:
En el siguiente ejemplo se recuperan todos los cursos que contienen la palabra clave "exámenes" en el nombre del curso:
https://prod.ally.ac/api/v2/clients/15/reports/overall?courseName=co:tests
Uso de múltiples filtros
Puede combinar las opciones de orden y filtrado en la misma URL del extremo, agregando el carácter "&" entre las dos condiciones. Por ejemplo, supongamos que desea recuperar todos los cursos que contienen la palabra clave "examen" en el nombre del curso donde Ally está habilitado y que la puntuación general es inferior al 90 %. La URL se vería así:
https://prod.ally.ac/api/v2/clients/0/overall?courseName=co:test&allyEnabled=true&overallScore=lt:0.9
También puede utilizar dos opciones de filtrado. Por ejemplo, supongamos que necesita obtener todos los cursos que tienen una puntuación general entre el 10 % y el 70 %:
https://prod.ally.ac/api/v2/clients/0/reports/overall?overallScore=ge:0.1&overallScore=le:0.7