En este artículo se presenta el uso de las API de Data Hub para recuperar un conjunto de datos avanzado y se proporciona un ejemplo práctico del proceso.
Data Hub aloja las exportaciones de datos de Brightspace. Data Hub contiene una selección de conjuntos de datos que los usuarios autorizados pueden ejecutar y exportar a CSV.
Una vez que se haya habilitado Data Hub para su instancia de Brightspace, puede acceder a él en Brightspace o a través de la API.
¿Qué información puedo obtener actualmente de Data Hub?
Actualmente, los clientes principales pueden acceder a siete conjuntos de datos avanzados: Todos los grados, Evaluación de los resultados de aprendizaje del curso (CLOE), Uso del instructor, Uso del alumno, Historial de sesiones suplantadas, Inscripciones y retiros y Calificaciones finales. Además, los conjuntos de datos de Brightspace también se encuentran en el centro de datos, pero están fuera del alcance de este artículo. Refiérase a Cómo comenzar a usar las API de Data Hub: Conjuntos de datos de Brightspace para obtener información adicional.
¿Cómo accedo a Data Hub?
Se puede acceder a Data Hub en Brightspace. Se puede agregar un enlace de Data Hub a su barra de navegación para mayor comodidad. Como alternativa, también puede navegar a /d2l/datahub/dataexport/list en el navegador.
También se puede acceder a Data Hub a través de la API. En las siguientes secciones, se explica cómo acceder a Data Hub a través de la API.
¿Cuál es el flujo esperado al usar la API de Data Hub?
Nota: La autorización no se trata en esta sección. Consulte el tutorial de código a continuación o el Token de actualización para obtener más información.
Las rutas a continuación están documentadas dentro de nuestro Referencia de la API documentación.
En primer lugar, decida qué conjunto de datos desea ejecutar. Puede usar /d2l/api/lp/1.13/dataExport/list para ver todos los conjuntos de datos disponibles. Un ejemplo de respuesta puede ser el siguiente:
[
{
DataSetId: "ff842aae-84d0-4e39-9db4-3ae51d36bb0e",
Denominación: "Notas finales",
Descripción: "El conjunto de datos de calificaciones finales devuelve las calificaciones finales de todos los alumnos en las ofertas de cursos".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "startDate",
Tipo: 1
},
{
Nombre: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "c1bf7603-669f-4bef-8cf4-651b914c4678",
Nombre: "Inscripciones y Retiros",
Descripción: "Un conjunto de datos de inscripciones y retiros que consta de atributos de unidad de organización, usuario y rol, junto con el estado de inscripción para un intervalo de fechas determinado".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "startDate",
Tipo: 1
},
{
Nombre: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "be5e86b8-9723-4ad7-af63-86783a77a1a1",
Nombre: "Todos los grados",
Descripción: "El conjunto de datos Todas las calificaciones devuelve las calificaciones de todos los elementos calificables para todos los alumnos en las ofertas de cursos".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "parentOrgUnitId",
Tipo: 2
},
{
Nombre: "startDate",
Tipo: 1
},
{
Nombre: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "c195aa85-b2be-4444-aa52-570e19bfee9e",
Nombre: "Uso del alumno",
Descripción: "El conjunto de datos Uso del alumno devuelve la actividad para todos los alumnos en las ofertas de cursos".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "parentOrgUnitId",
Tipo: 2
},
{
Nombre: "startDate",
Tipo: 1
},
{
Nombre: "endDate",
Tipo: 1
},
{
Nombre: "roles",
Tipo: 3
}
]
},
{
DataSetId: "76351c8d-e7dc-4b43-844a-14eb2c02193d",
Nombre: "Historial de sesiones suplantado",
Descripción: "El conjunto de datos Historial de sesiones suplantadas devuelve todas las sesiones suplantadas para un usuario específico o para todos los usuarios en un intervalo de fechas".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "userId",
Tipo: 4
},
{
Nombre: "startDate",
Tipo: 1
},
{
Nombre: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "af389020-439b-4d54-969e-edb9ff243a47",
Nombre: "CLOE",
Descripción: "El conjunto de datos de evaluación de resultados de aprendizaje del curso devuelve los resultados del alumno para las competencias requeridas".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "parentOrgUnitId",
Tipo: 2
},
{
Nombre: "roles",
Tipo: 3
}
]
},
{
DataSetId: "df7d0ef3-bcab-4171-bc37-5929d5867cd8",
Nombre: "Uso del instructor",
Descripción: "El informe de uso del instructor proporciona información sobre cómo los instructores utilizan la funcionalidad de LMS dentro de sus cursos".
Categoría: "AdvancedDataSets",
Filtros:
[
{
Nombre: "parentOrgUnitId",
Tipo: 2
},
{
Nombre: "startDate",
Tipo: 1
},
{
Nombre: "endDate",
Tipo: 1
},
{
Nombre: "roles",
Tipo: 3
}
]
}
]
Esta respuesta significa que hay seis conjuntos de datos disponibles y enumera los filtros utilizados para cada uno. Por ejemplo, el conjunto de datos CLOE toma una entrada de ParentOrgUnitId y Roles para los filtros.
Digamos que queremos correr Inscripciones y retiros. Tomamos el DataSetId de arriba ( c1bf7603-669f-4bef-8cf4-651b914c4678 ) y ejecutamos el trabajo enviando un POST a /d2l/api/lp/1.13/dataExport/create.
{
"DataSetId": "c1bf7603-669f-4bef-8cf4-651b914c4678",
"Filtros": [
{
"name": "startDate",
"value": "2015-08-05T00:00:00.000Z"
},
{
"name": "endDate",
"value": "2016-08-05T23:59:59.999Z"
}
]
}
Esto le indicará a Data Hub que cree un conjunto de datos de inscripciones y retiros con datos del 5 de agosto de 2015 al 5 de agosto de 2016.
Nota: Solo se admite la zona horaria UTC.
La ruta de creación devolverá un ID de trabajo de exportación que puede usar para consultar el estado del trabajo de exportación.
{
"ExportJobId": "7699bad4-0ae1-4772-8960-390081d2feea",
"DataSetId": "c1bf7603-669f-4bef-8cf4-651b914c4678",
"Nombre": "Inscripciones y Retiros",
"SubmitDate": "2016-08-05T18:28:47.130Z",
"Estado": 0,
"Categoría": "Perspectivas"
}
Usando el identificador de la creación del trabajo de exportación, podemos ver su estado usando /d2l/api/lp/1.13/dataExport/jobs/7699bad4-0ae1-4772-8960-390081d2feea.
{
"ExportJobId": "7699bad4-0ae1-4772-8960-390081d2feea",
"DataSetId": "c1bf7603-669f-4bef-8cf4-651b914c4678",
"Nombre": "Inscripciones y Retiros",
"SubmitDate": "2016-08-05T18:28:47.130Z",
"Estado": 2,
"Categoría": "Perspectivas"
}
Nota: El Estado es ahora 2 lo que significa que el trabajo se completó con éxito. Además de consultar el estado de un trabajo específico, también podemos ver todos los trabajos anteriores usando /d2l/api/lp/1.13/dataExport/jobs.
Dado que el estado de nuestro trabajo de exportación es ahora Íntegro A continuación, podemos descargar los datos utilizando la ruta de descarga y el ExportJobId desde arriba /d2l/api/lp/1.13/dataExport/download/7699bad4-0ae1-4772-8960-390081d2feea.
Tutorial de ejemplo de código
Hemos creado un archivo Ejemplo de aplicación para ayudar a los desarrolladores a empezar a usar la API de Data Hub. En la siguiente sección se recorrerán secciones importantes del código.
Para ejecutar la aplicación, primero necesitamos un token de actualización (que se obtiene siguiendo las instrucciones de la entrada de blog Token de actualización). Una vez que tengamos un token de actualización, debemos cambiarlo por un token de acceso.
En primer lugar, lea el token de actualización de un archivo.
Ruta refreshTokenPath = Paths.get(refreshTokenFile);
Cadena oldRefreshToken = Files.readAllLines(refreshTokenPath).get(0);
A continuación, cree nuestra cadena de autorización a partir de nuestro ID de cliente y secreto de cliente. Esto permite que el servicio de autorización sepa qué aplicación somos.
Cadena authHeaderValue = getClientAuthHeaderValue(clientId, clientSecret);
A continuación, creamos la solicitud y POST en el servicio de autorización.
Carga útil de la lista = Form.form()
.add("grant_type", "refresh_token")
.add("refresh_token", oldRefreshToken)
.construir();
Respuesta de HttpResponse = Post(tokenEndpoint)
.setHeader(HttpHeaders.AUTHORIZATION, authHeaderValue)
.bodyForm(carga útil)
.ejecutar()
.returnResponse();
El servicio de autorización nos devuelve el token de acceso. Enviaremos este token con nuestras solicitudes de API de Data Hub.
JsonObject responseJson = httpResponseToJsonObject(respuesta);
Cadena accessToken = responseJson
.get("access_token")
.getAsString();
Por último, guardamos el nuevo token de actualización en un archivo. La próxima vez que ejecutemos la aplicación, necesitaremos este token de actualización para obtener otro token de acceso.
Cadena newRefreshToken = responseJson
.get("refresh_token")
.getAsString();
Files.write(refreshTokenPath, newRefreshToken.getBytes());
En esta aplicación de ejemplo se supone que ya hemos llamado a la ruta para ver todos los conjuntos de datos. Para completar, queremos asegurarnos de que el conjunto de datos (en este caso, Inscripciones y retiros) existe. Para ello, consultamos la API del centro de datos mediante el ID del conjunto de datos.
private static void assertDataSetIdExists(
Cadena accessToken,
Cadena hostUrl,
String dataSetId) throws IOException {
makeGetRequest(accessToken,
format("%s/d2l/api/lp/1.13/dataExport/list/%s", hostUrl, dataSetId),
format("no se puede encontrar el conjunto de datos especificado [dataSetId = %s]", dataSetId));
}
Ahora que sabemos que el conjunto de datos existe, podemos enviar un trabajo de exportación para que se procese. Para ello, enviamos un POST a la API de Data Hub que contiene información sobre el conjunto de datos para el que queremos datos y las fechas en las que se filtran los datos. La API de Data Hub devolverá información sobre el trabajo de exportación enviado, incluido el ID del trabajo de exportación.
Cadena estática privada submitExportJob(
Cadena accessToken,
Cadena hostUrl,
Cadena dataSetId,
Cadena startDate,
String endDate) lanza IOException {
String bodyString = format(
"{\"DataSetId\": \"%s\", \"Filtros\": [{\"Nombre\": \"FechaInicio\", \"Valor\": \"%s\"}, {\"Nombre\": \"FechaFinal\", \"Valor\": \"%s\"}]}",
dataSetId, startDate, endDate);
Respuesta HttpResponse = makePostRequest(
accessToken,
format("%s/d2l/api/lp/1.13/dataExport/create", hostUrl),
bodyString,
format("no se puede crear trabajo [requestBody = %s]", bodyString)
);
Cadena exportJobId = httpResponseToJsonObject(respuesta)
.get("ExportJobId")
.getAsString();
return exportJobId;
}
Con el ID de trabajo de exportación del paso anterior, podemos comprobar periódicamente el estado de nuestro trabajo de exportación mediante la API de Data Hub. Se llama a la siguiente función cada 10 segundos para asegurarse de que el trabajo sigue en cola, se está procesando o se ha completado.
private static int doPollForCompletedExportJob(
Cadena accessToken,
Cadena hostUrl,
String exportJobId) throws IOException {
Respuesta HttpResponse = makeGetRequest(
accessToken,
format("%s/d2l/api/lp/1.13/dataExport/jobs/%s", hostUrl, exportJobId),
format("no se puede comprobar el estado del trabajo de exportación [exportJobId = %s]", exportJobId)
);
int status = httpResponseToJsonObject(respuesta)
.get("Estado")
.getAsInt();
assertValidStatus(exportJobId, estado);
estado de devolución;
}
Finalmente, nuestro trabajo de exportación se ha completado con éxito. Ahora podemos descargar el archivo ZIP que contiene nuestro CSV utilizando la API de Data Hub.
private static void downloadCompletedExportJob(
Cadena accessToken,
Cadena hostUrl,
Cadena exportJobId,
String outputFolder) lanza IOException {
Archivo tempFile = createTempFile(
exportJobId,
".zip",
new File(outputFolder)
);
try (FileOutputStream fileOutputStream = new FileOutputStream(tempFile)) {
makeGetRequest(
accessToken,
formato(
"%s/d2l/api/lp/1.13/dataExport/download/%s",
hostUrl,
exportJobId
),
formato(
"no se puede descargar el trabajo de exportación [exportJobId = %s]",
exportJobId
)
)
.getEntity()
.writeTo(fileOutputStream);
}
}
¿Necesita más ayuda para trabajar con datos? ¿Atascado en alguno de los pasos anteriores? ¿Le falta uno de los conjuntos de habilidades necesarios? D2L proporciona niveles flexibles de servicios de Learning Analytics que pueden ayudar con cualquiera o todos los pasos del proceso detallado en esta publicación. Si está interesado, póngase en contacto con su representante de éxito del cliente de D2L.