Cet article présente l’utilisation des API Data Hub pour récupérer un ensemble de données avancé et donne un exemple pratique à l’aide du processus.
Data Hub héberge les exportations de données de Brightspace. Data Hub contient une sélection d’ensembles de données que les utilisateurs autorisés peuvent exécuter et exporter vers CSV.
Une fois que Data Hub a été activé pour votre instance Brightspace, vous pouvez y accéder dans Brightspace ou via l’API.
Quelles informations puis-je actuellement obtenir de Data Hub ?
Actuellement, les clients principaux peuvent accéder à sept ensembles de données avancés - Tous les grades, Évaluation des résultats d’apprentissage du cours (CLOE), Utilisation de l’instructeur, Utilisation par l’apprenant, Historique de session usurpé, Inscriptions et retraits et Notes finales. En outre, les ensembles de données Brightspace se trouvent également dans le Data Hub mais sortent du cadre de cet article. Reportez-vous à la section Comment commencer avec les API de Data Hub : Brightspace Data Sets pour de plus amples renseignements.
Comment puis-je accéder au Data Hub ?
Data Hub est accessible dans Brightspace. Un lien Data Hub peut être ajouté à votre barre de navigation pour plus de commodité. Vous pouvez également accéder à /d2l/datahub/dataexport/list dans votre navigateur.
Data Hub est également accessible via l’API. Les sections suivantes vous guideront tout au long de l’accès à Data Hub via l’API.
Quel est le flux attendu lors de l’utilisation de l’API de Data Hub ?
Remarque : L’autorisation n’est pas traitée dans cette section. Consultez la procédure pas à pas du code ci-dessous ou le jeton d’actualisation article de blog pour plus d’informations.
Les itinéraires ci-dessous sont documentés dans notre Référence de l’API la documentation.
Tout d’abord, décidez de l’ensemble de données que vous souhaitez exécuter. Vous pouvez utiliser /d2l/api/lp/1.13/dataExport/list pour voir tous les ensembles de données disponibles. Un exemple de réponse peut ressembler à ce qui suit :
[
{
DataSetId : « ff842aae-84d0-4e39-9db4-3ae51d36bb0e »,
Nom : « Notes finales »,
Description : « L’ensemble de données sur les notes finales renvoie les notes finales pour tous les apprenants dans les cours offerts. »,
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « startDate »,
Type : 1
},
{
Nom : « endDate »,
Type : 1
}
]
},
{
DataSetId : « c1bf7603-669f-4bef-8cf4-651b914c4678 »,
Nom : « Inscriptions et retraits »,
Description : « Un ensemble de données d’inscriptions et de retraits composé d’attributs d’unité d’organisation, d’utilisateur et de rôle, ainsi que l’état d’inscription pour une plage de dates donnée. »,
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « startDate »,
Type : 1
},
{
Nom : « endDate »,
Type : 1
}
]
},
{
DataSetId : « be5e86b8-9723-4ad7-af63-86783a77a1a1 »,
Nom : « Tous les grades »,
Description : « L’ensemble de données Toutes les notes renvoie les notes pour tous les éléments gradables pour tous les apprenants dans les offres de cours. »
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « parentOrgUnitId »,
Type : 2
},
{
Nom : « startDate »,
Type : 1
},
{
Nom : « endDate »,
Type : 1
}
]
},
{
DataSetId : « c195aa85-b2be-4444-aa52-570e19bfee9e »,
Nom : « Utilisation par l’apprenant »,
Description : « L’ensemble de données sur l’utilisation de l’apprenant renvoie l’activité pour tous les apprenants dans les offres de cours. »,
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « parentOrgUnitId »,
Type : 2
},
{
Nom : « startDate »,
Type : 1
},
{
Nom : « endDate »,
Type : 1
},
{
Nom : « rôles »,
Type : 3
}
]
},
{
DataSetId : « 76351c8d-e7dc-4b43-844a-14eb2c02193d »,
Nom : « Historique de session usurpé d’identité »,
Description : « L’ensemble de données d’historique de session usurpé renvoie toutes les sessions usurpées pour un utilisateur spécifique ou tous les utilisateurs sur une plage de dates. »,
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « userId »,
Type : 4
},
{
Nom : « startDate »,
Type : 1
},
{
Nom : « endDate »,
Type : 1
}
]
},
{
DataSetId : « af389020-439b-4d54-969e-edb9ff243a47 »,
Nom : « CLOE »,
Description : « L’ensemble de données de l’évaluation des résultats d’apprentissage du cours renvoie les résultats de l’apprenant pour les compétences requises. »
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « parentOrgUnitId »,
Type : 2
},
{
Nom : « rôles »,
Type : 3
}
]
},
{
DataSetId : « df7d0ef3-bcab-4171-bc37-5929d5867cd8 »,
Nom : « Utilisation de l’instructeur »,
Description : « Le rapport d’utilisation de l’instructeur fournit des informations sur la façon dont les instructeurs utilisent la fonctionnalité LMS dans leurs cours. »
Catégorie : « AdvancedDataSets »,
Filtres :
[
{
Nom : « parentOrgUnitId »,
Type : 2
},
{
Nom : « startDate »,
Type : 1
},
{
Nom : « endDate »,
Type : 1
},
{
Nom : « rôles »,
Type : 3
}
]
}
]
Cette réponse signifie qu’il existe six ensembles de données disponibles et répertorie les filtres utilisés pour chacun d’eux. Par exemple, le jeu de données CLOE prend une entrée de ParentOrgUnitId et Roles pour les filtres.
Dites que nous voulons courir Inscriptions et retraits. Nous prenons le DataSetId d’en haut ( c1bf7603-669f-4bef-8cf4-651b914c4678 ) et exécutez le travail en envoyant un POST à /d2l/api/lp/1.13/dataExport/create.
{
« DataSetId » : « c1bf7603-669f-4bef-8cf4-651b914c4678 »,
« Filtres » : [
{
« name » : « startDate »,
« valeur » : « 2015-08-05T00:00:00.000Z »
},
{
« name » : « endDate »,
« valeur » : « 2016-08-05T23:59:59.999Z »
}
]
}
Cela indiquera à Data Hub de créer un ensemble de données inscriptions et retraits avec des données du 5 août 2015 au 5 août 2016.
Remarque :: seul le fuseau horaire UTC est pris en charge.
L’itinéraire de création renvoie un ID de tâche d’exportation que vous pouvez utiliser pour interroger l’état de votre tâche d’exportation.
{
« ExportJobId » : « 7699bad4-0ae1-4772-8960-390081d2feea »,
« DataSetId » : « c1bf7603-669f-4bef-8cf4-651b914c4678 »,
« Nom » : « Inscriptions et retraits »,
« SubmitDate » : « 2016-08-05T18:28:47.130Z »,
« Statut » : 0,
« Catégorie » : « Aperçus »
}
En utilisant l’identificateur de la création de la tâche d’exportation, nous pouvons afficher son statut à l’aide de /d2l/api/lp/1.13/dataExport/jobs/7699bad4-0ae1-4772-8960-390081d2feea.
{
« ExportJobId » : « 7699bad4-0ae1-4772-8960-390081d2feea »,
« DataSetId » : « c1bf7603-669f-4bef-8cf4-651b914c4678 »,
« Nom » : « Inscriptions et retraits »,
« SubmitDate » : « 2016-08-05T18:28:47.130Z »,
« Statut » : 2,
« Catégorie » : « Aperçus »
}
Remarque : L' État d’avancement est maintenant 2 ce qui signifie que le travail s’est terminé avec succès. En plus d’interroger l’état d’une tâche spécifique, nous pouvons également afficher tous les travaux passés à l’aide de /d2l/api/lp/1.13/dataExport/jobs.
Puisque le statut de notre travail d’exportation est maintenant Terminé nous pouvons ensuite télécharger les données en utilisant l’itinéraire de téléchargement et le ExportJobId ci-dessus /d2l/api/lp/1.13/dataExport/download/7699bad4-0ae1-4772-8960-390081d2feea.
Exemple de code Procédure pas à pas
Nous avons créé un exemple d’application pour aider les développeurs à commencer à utiliser l’API Data Hub. La section suivante passera en revue les sections importantes du code.
Pour exécuter l’application, nous avons d’abord besoin d’un jeton d’actualisation (obtenu en suivant les instructions du blog Refresh Token). Une fois que nous avons un jeton d’actualisation, nous devons l’échanger contre un jeton d’accès.
Tout d’abord, lisez le jeton d’actualisation d’un fichier.
Chemin refreshTokenPath = Paths.get(refreshTokenFile) ;
Chaîne oldRefreshToken = Files.readAllLines(refreshTokenPath).get(0) ;
Créez ensuite notre chaîne d’autorisation à partir de notre ID client et de notre secret client. Cela permet au service d’autorisation de savoir quelle application nous sommes.
String authHeaderValue = getClientAuthHeaderValue(clientId, clientSecret) ;
Ensuite, nous créons la demande et postons au service d’autorisation.
Liste des charges utiles = Form.form()
.add(« grant_type », « refresh_token »)
.add(« refresh_token », oldRefreshToken)
.build() ;
Réponse httpResponse = Post(tokenEndpoint)
.setHeader(HttpHeaders.AUTHORIZATION, authHeaderValue)
.bodyForm(charge utile)
.execute()
.returnResponse() ;
Le service d’autorisation nous renvoie le jeton d’accès. Nous enverrons ce jeton avec nos demandes d’API Data Hub.
JsonObject responseJson = httpResponseToJsonObject(response) ;
String accessToken = responseJson
.get(« access_token »)
.getAsString() ;
Enfin, nous enregistrons le nouveau jeton d’actualisation dans le fichier. La prochaine fois que nous exécuterons l’application, nous aurons besoin de ce jeton d’actualisation pour obtenir un autre jeton d’accès.
Chaîne newRefreshToken = responseJson
.get(« refresh_token »)
.getAsString() ;
Files.write(refreshTokenPath, newRefreshToken.getBytes()) ;
Cet exemple d’application suppose que nous avons déjà appelé l’itinéraire pour voir tous les ensembles de données. Par souci d’exhaustivité, nous voulons nous assurer que l’ensemble de données (dans ce cas, Inscriptions et retraits) existe. Pour ce faire, nous interrogeons l’API Data Hub à l’aide de l’ID de l’ensemble de données.
vide statique privé assertDataSetIdExists(
Accès à la chaîneToken,
Chaîne hostUrl,
String dataSetId) lance IOException {
makeGetRequest(accessToken,
format(« %s/d2l/api/lp/1.13/dataExport/list/%s », hostUrl, dataSetId),
format(« impossible de trouver l’ensemble de données spécifié [dataSetId = %s] », dataSetId)) ;
}
Maintenant que nous savons que l’ensemble de données existe, nous pouvons soumettre une tâche d’exportation à traiter. Pour ce faire, nous envoyons un POST à l’API Data Hub contenant des informations sur l’ensemble de données pour lequel nous voulons des données et les dates auxquelles les données sont filtrées. L’API Data Hub renvoie des informations sur la tâche d’exportation soumise, y compris l’ID de tâche d’exportation.
chaîne statique privée submitExportJob(
Accès à la chaîneToken,
Chaîne hostUrl,
String dataSetId,
Chaîne startDate,
String endDate) lance IOException {
String bodyString = format(
« {\"DataSetId\ » : \"%s\ », \"Filters\ » : [{\"Name\ » : \"startDate\ », \"Value\ » : \"%s\"}, {\"Name\ » : \"endDate\ », \"Value\ » : \"%s\"}]} »,
dataSetId, startDate, endDate) ;
HttpResponse response = makePostRequest(
accessToken,
format(« %s/d2l/api/lp/1.13/dataExport/create », hostUrl),
bodyString,
format(« impossible de créer un travail [requestBody = %s] », bodyString)
);
String exportJobId = httpResponseToJsonObject(response)
.get(« ExportJobId »)
.getAsString() ;
retour exportJobId ;
}
Avec l’ID de travail d’exportation de l’étape précédente, nous pouvons vérifier périodiquement l’état de notre travail d’exportation à l’aide de l’API Data Hub. La fonction ci-dessous est appelée toutes les 10 secondes pour s’assurer que la tâche est toujours en file d’attente, traitée ou terminée.
private static int doPollForCompletedExportJob(
Accès à la chaîneToken,
Chaîne hostUrl,
String exportJobId) lance IOException {
Réponse httpresponse = makeGetRequest(
accessToken,
format(« %s/d2l/api/lp/1.13/dataExport/jobs/%s », hostUrl, exportJobId),
format(« impossible de vérifier l’état du travail d’exportation [exportJobId = %s] », exportJobId)
);
int status = httpResponseToJsonObject(response)
.get(« Statut »)
.getAsInt() ;
assertValidStatus(exportJobId, statut) ;
l’état du retour ;
}
Enfin, notre travail d’exportation s’est terminé avec succès. Nous pouvons maintenant télécharger le fichier ZIP contenant notre CSV à l’aide de l’API Data Hub.
téléchargement vide statique privéCompletedExportJob(
Accès à la chaîneToken,
Chaîne hostUrl,
Chaîne exportJobId,
String outputFolder) lance IOException {
Fichier tempFile = createTempFile(
exportJobId,
« .zip »,
nouveau fichier(outputFolder)
);
try (FileOutputStream fileOutputStream = new FileOutputStream(tempFile)) {
makeGetRequest(
accessToken,
format(
« %s/d2l/api/lp/1.13/dataExport/download/%s »,
hostUrl,
exportJobId
),
format(
« impossible de télécharger le travail d’exportation [exportJobId = %s] »,
exportJobId
)
)
.getEntity()
.writeTo(fileOutputStream) ;
}
}
Besoin d’aide supplémentaire pour travailler avec les données ? Coincé sur l’une des étapes ci-dessus ? Vous manquez l’un des ensembles de compétences nécessaires ? D2L fournit des niveaux flexibles de services d’analyse de l’apprentissage qui peuvent vous aider à toutes les étapes du processus détaillé dans cet article. Si vous êtes intéressé, veuillez contacter votre représentant D2L Customer Success.