Reporting API Endpoints

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 ver 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. Se describen en la siguiente sección:

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 de EE. UU.: prod.ally.ac
• Centro de datos de Canadá: prod-ca-central-1.ally.ac
• Centro de datos de Europa: prod-eu-central-1.ally.ac
• Centro de datos de Singapur: prod-ap-southeast-1.ally.ac
• Centro de datos de Australia: prod-ap-southeast-2.ally.ac

La información anterior puede variar según el LMS. Puede revisar la definición de la columna en la Documentación del informe del curso para cada LMS:

• Blackboard Learn
• Moodle
• Brightspace de D2L
• Instructure Canvas

Respuesta de estado HTTP

La API de Ally incluye un campo de estado en los metadatos que puede mostrar lo siguiente:

• Estado 200: Se realizó correctamente. La solicitud se recibió correctamente y el conjunto de datos solicitado forma parte de la respuesta.
• Estado 202: En proceso. La solicitud se recibió correctamente, pero el conjunto de datos está en preparación y aún no se encuentra disponible. Espere un momento antes de repetir la solicitud (se recomienda que sea al menos un minuto).
• Estado 401: No autorizado. El ID de cliente de Ally o el token de autorización no son correctos.
• Estado 400: Solicitud incorrecta. Hay un nombre de parámetro no válido en la URL, por ejemplo, una opción, un operador o un valor de filtro desconocido. Revise la sintaxis de la URL. Recuerde que algunas de las opciones de filtro y orden distinguen entre mayúsculas y minúsculas.

Documentación de métodos

Método: 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 de EE. UU.: prod.ally.ac
• Centro de datos de Canadá: prod-ca-central-1.ally.ac
• Centro de datos de Europa: prod-eu-central-1.ally.ac
• Centro de datos de Singapur: prod-ap-southeast-1.ally.ac
• Centro de datos de Australia: prod-ap-southeast-2.ally.ac

Autorización: Token portador de OAuth

Parámetros: Opciones de orden y filtros opcionales.

Cuerpo de la solicitud: Ninguno

Respuesta:

{ 
    "data": [ 
        { 
            "application/x-quiz": 2, 
            "observedDeletedOn": "", 
            "termName":"Otoño 2016", 
            "courseId": "1", 
            "application/x-announcement":0, 
           "image": 4, 
            "termId": "2", 
            "document":93, 
            "allyEnabled": true 
            "pdf":74, 
            "courseCode":"BIO101", 
            "application/x-assignment":0, 
            "departmentld":"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": "Biología 101", 
            "application/x-discussion-topic": 1, 
            "other": 11, 
            "overallScore": 0.6129724428830603, 
            "presentation": 5 
        } 
], 
    "metadata": {
    "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "En proceso", 
        "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 de EE. UU.: prod.ally.ac
• Centro de datos de Canadá: prod-ca-central-1.ally.ac
• Centro de datos de Europa: prod-eu-central-1.ally.ac
• Centro de datos de Singapur: prod-ap-southeast-1.ally.ac
• Centro de datos de Australia: prod-ap-southeast-2.ally.ac

Autorización: Token portador de OAuth

Parámetros: Filtros opcionales u opciones de orden.

Cuerpo de la solicitud: Ninguno

Respuesta: 

{ 
    "data": [ 
        { 
            "imageDecorative2": 4, 
            "htmlEmptyHeading2": 0, 
            "imageSeizure1": 2, 
            "observedDeletedOn": "", 
           "htmlObjectAlt2": 0, 
            "security1": 3, 
            "termName":"Otoño 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":"Biología 101", 
            "imageContrast2":0, 
            "imageDescription2": 4, 
            "htmlTitle3": 1, 
            "parsable1": 2 
        } 
], 
    "metadata": { 
        "filteredTotal": 0,
    "total": 7186,
        "to": 7186,
    "status": "En proceso", 
        "from": 1 
    } 
} ;

Donde: 

• Datos: contiene el conjunto de datos de los resultados.
• Metadatos: 
  • Hasta: El registro del que se obtendrán los datos es "desplazamiento" + "límite" o "total" si la suma excede "total". 
  • Desde: El registro del cual iniciarán los datos es "desplazamiento" + 1. 
  • Total: Cantidad total de cursos considerados por Ally en la instancia de LMS. 

Desplazamiento desde el cual se inicia el registro 

• 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), el usuario obtiene el error 400 [Valor no válido (parámetro = desplazado, mensaje = No hay datos)] 

Límite: la cantidad de registros que se recuperan a partir del desplazamiento 

• 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 > 10 000), el usuario obtiene el error 400 [Valor no válido (parámetro = límite, mensaje = Fuera de los límites)] 
• Cuando (desplazamiento < total; desplazamiento + límite > total), cambiamos el límite en segundo plano y se recuperan todos los datos (total) 

Filtros y opciones de orden 

Las respuestas del extremo se pueden filtrar en la URL. En esta tabla se describen las opciones disponibles: 

Opciones de orden 

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= 

Donde puede ser cualquiera de los siguientes valores: 

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 siguiente parámetro de orden: 

endpoint-url?sort=&order= 

Donde puede ser algunos de los siguientes: asc or desc 

Ejemplo: 

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

Opciones de filtrado 

Puede utilizar las opciones de filtrado para obtener respuestas más pequeñas o reducidas en función de los criterios seleccionados. Si necesita agregar una opción de filtrado, debe agregar el parámetro de filtro como se describe a continuación:

Parámetros de filtro (sin operador) 

 endpoint-url?= 

Parámetros de filtro (con operador) 

endpoint-url?=: 

Donde: 

• Parámetro de filtro: Parámetro de filtrado para obtener un conjunto de resultados más pequeño. Puede consultar los parámetros compatibles en la siguiente tabla. 
• Operador: Debe usar un operador para filtrar, como igual o no igual. 
• Valor: Valor utilizado en el filtro. 

Los valores de los parámetros distinguen mayúsculas y minúsculas.

Operadores compatibles

En la siguiente tabla se incluyen los operadores compatibles en función del tipo de campo: 

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 varios 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