Este artigo apresenta o uso das APIs do Data Hub para recuperar um conjunto de dados avançado e fornece um exemplo prático usando o processo.
O Data Hub hospeda exportações de dados do Brightspace. O Data Hub contém uma seleção de conjuntos de dados que os usuários autorizados podem executar e exportar para CSV.
Depois que o Data Hub for ativado para sua instância do Brightspace, você poderá acessá-lo no Brightspace ou por meio da API.
Quais informações posso obter atualmente do Data Hub?
Atualmente, os clientes Core podem acessar sete conjuntos de dados avançados – Todas as séries, Avaliação dos Resultados de Aprendizagem do Curso (CLOE), Uso do instrutor, Uso do aluno, Histórico de sessões representadas, Inscrições e Desistências e Notas finais. Além disso, os conjuntos de dados do Brightspace também estão localizados no Hub de dados, mas estão fora do escopo deste artigo. Referir-se a Como começar a usar as APIs do Data Hub: Conjuntos de dados do Brightspace para obter informações adicionais.
Como faço para acessar o Data Hub?
O Data Hub pode ser acessado no Brightspace. Um link do Data Hub pode ser adicionado à sua barra de navegação para maior conveniência. Como alternativa, você também pode navegar até /d2l/datahub/dataexport/list em seu navegador.
O Data Hub também pode ser acessado via API. As seções a seguir orientarão você no acesso ao Data Hub por meio da API.
Qual é o fluxo esperado ao usar a API do Data Hub?
Nota: A autorização não é abordada nesta seção. Veja o passo a passo do código abaixo ou o Token de atualização para obter mais informações.
As rotas abaixo estão documentadas em nosso Referência de API documentação.
Primeiro, decida qual conjunto de dados você gostaria de executar. Você pode usar /d2l/api/lp/1.13/dataExport/list para ver todos os conjuntos de dados disponíveis. Um exemplo de resposta pode ser semelhante ao seguinte:
[
{
DataSetId: "ff842aae-84d0-4e39-9db4-3ae51d36bb0e",
Nome: "Notas Finais",
Descrição: "O conjunto de dados de notas finais retorna notas finais para todos os alunos nas ofertas de cursos.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "startDate",
Tipo: 1
},
{
Nome: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "c1bf7603-669f-4bef-8cf4-651b914c4678",
Nome: "Matrículas e Desistências",
Descrição: "Um conjunto de dados de Inscrições e Retiradas que consiste nos atributos Unidade organizacional, Usuário e Função, juntamente com o status de inscrição para um determinado intervalo de datas.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "startDate",
Tipo: 1
},
{
Nome: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "be5e86b8-9723-4ad7-af63-86783a77a1a1",
Nome: "Todas as séries",
Descrição: "O conjunto de dados Todas as notas retorna as notas de todos os itens avaliáveis de todos os alunos nas ofertas de curso.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "parentOrgUnitId",
Tipo: 2
},
{
Nome: "startDate",
Tipo: 1
},
{
Nome: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "c195aa85-b2be-4444-aa52-570e19bfee9e",
Nome: "Uso do aluno",
Descrição: "O conjunto de dados Uso do aluno retorna a atividade para todos os alunos nas ofertas de curso.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "parentOrgUnitId",
Tipo: 2
},
{
Nome: "startDate",
Tipo: 1
},
{
Nome: "endDate",
Tipo: 1
},
{
Nome: "roles",
Tipo: 3
}
]
},
{
DataSetId: "76351c8d-e7dc-4b43-844a-14eb2c02193d",
Nome: "Histórico de Sessão Representado",
Descrição: "O conjunto de dados Histórico de Sessões Representadas retorna todas as sessões representadas para um ou todos os usuários específicos em um intervalo de datas.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "userId",
Tipo: 4
},
{
Nome: "startDate",
Tipo: 1
},
{
Nome: "endDate",
Tipo: 1
}
]
},
{
DataSetId: "af389020-439b-4d54-969e-edb9ff243a47",
Nome: "CLOE",
Descrição: "O conjunto de dados Avaliação dos resultados de aprendizagem do curso retorna os resultados do aluno para as competências necessárias.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "parentOrgUnitId",
Tipo: 2
},
{
Nome: "roles",
Tipo: 3
}
]
},
{
DataSetId: "df7d0ef3-bcab-4171-bc37-5929d5867cd8",
Nome: "Uso do instrutor",
Descrição: "O relatório de uso do instrutor fornece informações sobre como os instrutores estão usando a funcionalidade LMS em seus cursos.",
Categoria: "Conjuntos de Dados Avançados",
Filtros:
[
{
Nome: "parentOrgUnitId",
Tipo: 2
},
{
Nome: "startDate",
Tipo: 1
},
{
Nome: "endDate",
Tipo: 1
},
{
Nome: "roles",
Tipo: 3
}
]
}
]
Essa resposta significa que há seis conjuntos de dados disponíveis e lista os filtros usados para cada um. Por exemplo, o conjunto de dados CLOE usa uma entrada de ParentOrgUnitId e Roles para filtros.
Digamos que queremos correr Inscrições e Desistências. Pegamos o DataSetId de cima ( c1bf7603-669f-4bef-8cf4-651b914c4678 ) e executamos o trabalho enviando um POST para /d2l/api/lp/1.13/dataExport/create.
{
"DataSetId": "c1bf7603-669f-4bef-8cf4-651b914c4678",
"Filtros": [
{
"nome": "dataDeinício",
"value": "2015-08-05T00:00:00.000Z"
},
{
"nome": "endDate",
"valor": "2016-08-05T23:59:59.999Z"
}
]
}
Isso dirá ao Data Hub para criar um conjunto de dados de Inscrições e Retiradas com dados de 5 de agosto de 2015 a 5 de agosto de 2016.
Nota: Somente o fuso horário UTC é suportado.
A rota de criação retornará uma ID de trabalho de exportação que você pode usar para consultar o status do trabalho de exportação.
{
"ExportJobId": "7699bad4-0ae1-4772-8960-390081d2feea",
"DataSetId": "c1bf7603-669f-4bef-8cf4-651b914c4678",
"Nome": "Matrículas e Desistências",
"Data de envio": "2016-08-05T18:28:47.130Z",
"Status": 0,
"Categoria": "Insights"
}
Usando o identificador da criação do trabalho de exportação, podemos visualizar seu status 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",
"Nome": "Matrículas e Desistências",
"Data de envio": "2016-08-05T18:28:47.130Z",
"Status": 2,
"Categoria": "Insights"
}
Nota: O Estado é agora 2 o que significa que o trabalho foi concluído com sucesso. Além de consultar o status de um trabalho específico, também podemos visualizar todos os trabalhos anteriores usando /d2l/api/lp/1.13/dataExport/jobs.
Como o status do nosso trabalho de exportação agora é Completar Podemos então baixar os dados usando a rota de download e o ExportJobId acima /d2l/api/lp/1.13/dataExport/download/7699bad4-0ae1-4772-8960-390081d2feea.
Passo a passo de exemplo de código
Criamos um Exemplo de aplicação para ajudar os desenvolvedores a começar a usar a API do Data Hub. A seção a seguir percorrerá seções importantes do código.
Para executar o aplicativo, primeiro precisamos de um token de atualização (obtido seguindo as instruções na postagem do blog Token de Atualização). Assim que tivermos um token de atualização, precisamos trocá-lo por um token de acesso.
Primeiro, leia o token de atualização de um arquivo.
Caminho refreshTokenPath = Paths.get(refreshTokenFile);
String oldRefreshToken = Files.readAllLines(refreshTokenPath).get(0);
Em seguida, crie nossa string de autorização a partir de nosso ID do cliente e segredo do cliente. Isso permite que o serviço de autorização saiba qual aplicativo somos.
String authHeaderValue = getClientAuthHeaderValue(clientId, clientSecret);
Em seguida, criamos a solicitação e o POST para o serviço de autorização.
Carga útil da lista = Form.form()
.add("grant_type", "refresh_token")
.add("refresh_token", oldRefreshToken)
.build();
Resposta HttpResponse = Post(tokenEndpoint)
.setHeader(HttpHeaders.AUTHORIZATION, authHeaderValue)
.bodyForm(carga útil)
.execute()
.returnResponse();
O serviço de autorização retorna o token de acesso para nós. Enviaremos esse token com nossas solicitações de API do Data Hub.
JsonObject responseJson = httpResponseToJsonObject(resposta);
String accessToken = responseJson
.get("access_token")
.getAsString();
Por fim, salvamos o novo token de atualização no arquivo. Na próxima vez que executarmos o aplicativo, precisaremos desse token de atualização para obter outro token de acesso.
String newRefreshToken = responseJson
.get("refresh_token")
.getAsString();
Files.write(refreshTokenPath, newRefreshToken.getBytes());
Este aplicativo de exemplo pressupõe que já chamamos a rota para ver todos os conjuntos de dados. Para completar, queremos ter certeza de que o conjunto de dados (neste caso, Inscrições e Desistências) existe. Fazemos isso consultando a API do Data Hub usando a ID do conjunto de dados.
private static void assertDataSetIdExists(
String accessToken,
String hostUrl,
String dataSetId) gera IOException {
makeGetRequest(accessToken,
format("%s/d2l/api/lp/1.13/dataExport/list/%s", hostUrl, dataSetId),
format("não é possível encontrar o conjunto de dados especificado [dataSetId = %s]", dataSetId));
}
Agora que sabemos que o conjunto de dados existe, podemos enviar um trabalho de exportação para ser processado. Fazemos isso enviando um POST para a API do Data Hub contendo informações sobre qual conjunto de dados queremos dados e por quais datas os dados são filtrados. A API do Data Hub retornará informações sobre o trabalho de exportação enviado, incluindo a ID do trabalho de exportação.
private static String submitExportJob(
String accessToken,
String hostUrl,
String dataSetId,
Data inicial da cadeia de caracteres,
String endDate) gera IOException {
String bodyString = format(
"{\"DataSetId\": \"%s\", \"Filtros\": [{\"Nome\": \"startDate\", \"Valor\": \"%s\"}, {\"Nome\": \"endDate\", \"Valor\": \"%s\"}]}",
dataSetId, startDate, endDate);
Resposta HttpResponse = makePostRequest(
accessToken,
format("%s/d2l/api/lp/1.13/dataExport/create", hostUrl),
corpo,
format("não é possível criar trabalho [requestBody = %s]", bodyString)
);
String exportJobId = httpResponseToJsonObject(resposta)
.get("ExportJobId")
.getAsString();
return exportJobId;
}
Com a ID do trabalho de exportação da etapa anterior, podemos verificar periodicamente o status do nosso trabalho de exportação usando a API do Data Hub. A função abaixo é chamada a cada 10 segundos para garantir que o trabalho ainda esteja enfileirado, processando ou concluído.
private static int doPollForCompletedExportJob(
String accessToken,
String hostUrl,
String exportJobId) gera IOException {
Resposta HttpResponse = makeGetRequest(
accessToken,
format("%s/d2l/api/lp/1.13/dataExport/jobs/%s", hostUrl, exportJobId),
format("não é possível verificar o status do trabalho de exportação [exportJobId = %s]", exportJobId)
);
int status = httpResponseToJsonObject(resposta)
.get("Status")
.getAsInt();
assertValidStatus(exportJobId, status);
status de retorno;
}
Finalmente, nosso trabalho de exportação foi concluído com sucesso. Agora podemos baixar o arquivo ZIP contendo nosso CSV usando a API do Data Hub.
download vazio estático privadoCompletedExportJob(
String accessToken,
String hostUrl,
String exportJobId,
String outputFolder) gera IOException {
Arquivo tempFile = createTempFile(
exportJobId,
".zip",
novo arquivo (outputFolder)
);
try (FileOutputStream fileOutputStream = new FileOutputStream(tempFile)) {
makeGetRequest(
accessToken,
formato(
"%s/d2l/api/lp/1.13/dataExport/download/%s",
hostUrl,
exportJobId
),
formato(
"não é possível baixar o trabalho de exportação [exportJobId = %s]",
exportJobId
)
)
.getEntity()
.writeTo(fileOutputStream);
}
}
Precisa de mais ajuda para trabalhar com dados? Preso em alguma das etapas acima? Faltando um dos conjuntos de habilidades necessários? A D2L fornece níveis flexíveis de serviços de análise de aprendizagem que podem ajudar em qualquer uma ou em todas as etapas do processo detalhadas nesta postagem. Se você estiver interessado, entre em contato com seu representante de Sucesso do Cliente da D2L.