Como administradores, podemos nos encontrar na situação de ter que baixar backups de cursos de anos anteriores, para trabalhar de acordo com as políticas de retenção de dados da nossa instituição.
Esses backups baixados podem então ser mantidos pelo tempo que for necessário em outro local habilitado para isso, como um bucket S3 da Amazon, uma pasta em um servidor da nossa instituição ou um disco rígido, sem afetar o espaço contratado para Blackboard.
No SaaS, os backups são criados automaticamente todos os dias e armazenados na Coleção de conteúdo para acesso durante 30 dias.
Para facilitar o download, a Blackboard criou um script que permite baixar para uma pasta local ou para um bucket S3 os backups em lote antes que desapareçam do servidor.
Os downloads são realizados por meio da REST API e, portanto, exigem algumas etapas anteriores ao uso, mas depois permitirão baixar sem utilizar credenciais de usuário. Esse script pode baixar os backups dos cursos incluídos em uma lista fornecida em um arquivo ou de todos os cursos criados entre duas datas especificadas.
O script não cria os backups, apenas os baixa. Se não existir um backup de um curso, ele não será baixado, mesmo que o curso esteja entre as datas especificadas ou no arquivo fornecido.
Preparando o aplicativo REST
Antes de mais nada, registraremos um aplicativo no Developer Portal (você pode aprender como registrar aplicativos e muito mais sobre a REST API aqui) e salvaremos os três parâmetros retornados: Application key, Secret e Application ID.
Preparando a Blackboard
Agora, acesse Painel do administrador > Integrações > Integrações de API REST e crie uma nova integração adicionando o Application ID que você copiou e atribuindo-a a um usuário com permissões suficientes para executar essa integração.
Recomendamos criar uma função específica para essa integração, com os privilégios mínimos necessários para realizar a tarefa, e utilizar um usuário criado para isso, ao qual seja atribuída a função de sistema que criamos.
Os privilégios necessários são:
- Permissão de leitura na Content Collection
- Permissão de arquivamento para cursos e organizações
- Permissão de arquivamento que inclui senhas para cursos e organizações
Deixe o restante das opções conforme definido por padrão e Salve.
Preparando o PC
Você precisará instalar o Python 3.8 ou superior, pip e também os pacotes requests e boto3. Baixe o script neste artigo de suporte.
Em poucas etapas, o script recebe um token com sua key e secret, lista os conteúdos de /internal/autoArchive e baixa o último arquivo de cada um dos cursos selecionados, juntamente com seu arquivo de registro. Quando termina, exibe um resumo do que foi realizado.
Se você colocar o secret como variável de ambiente, não precisará adicioná-lo sempre que executar o script e, além disso, ele não aparecerá no histórico do seu shell. Se preferir não adicioná-lo, o script solicitará o secret sempre que for executado.
No Linux, export AUTO_ARCHIVE_SECRET='<application secret>'
No Windows, $env:AUTO_ARCHIVE_SECRET = '<application secret>'.
Executando o script
Portanto, a invocação básica seria:
python3 auto_archive_bulk_download.py [--help] --site SITE --key KEY
[ --file FILE | --beginDate YYYY/MM/DD --endDate YYYY/MM/DD ]
[--debug] --output OUTPUT
Onde:
--help Imprimir a ajuda
--site SITE URL do ambiente Blackboard ao qual queremos acessar, incluindo o protocolo.
--key Key do aplicativo gerado no Developer portal
--file Caminho do arquivo de texto com a lista dos identificadores de curso. Obrigatório se as datas forem omitidas.
-- beginDate Data de criação dos cursos a partir da qual fazer o download, no formato AAAA/MM/DD
--endDate Data de criação dos cursos até a qual fazer o download, no formato AAAA/MM/DD
--debug Modo de depuração
--output Caminho onde salvar os backups. Pode ser local ou um S3.
Tenha em mente que:
- o script solicitará o secret utilizado no início da execução, a menos que você o salve em uma variável de ambiente
- o arquivo conterá apenas um courseID por linha, sem nenhum outro caractere ou separador
- se forem utilizadas datas, será necessário especificar ambas. Serão baixados todos os backups dos cursos criados entre as duas datas especificadas.
- os paths locais do output podem ser absolutos ou relativos, mas é importante que o diretório onde o download será realizado exista.
- Os arquivos de backup devem existir em /internal/autoArchive/ID-DO-CURSO. Se não existirem, o script não baixará nada e, ao finalizar, mostrará quais cursos estão nessa situação.
- o script baixará o backup mais recente de cada curso
- lembre-se de não executar várias instâncias do script em paralelo, pois isso geraria problemas de desempenho.
Ao finalizar, será exibido na tela um resumo do que foi realizado:
- Quantos backups foram baixados
- Cursos com erros e o motivo do erro
- Cursos com uma pasta vazia.
- Cursos com pasta, mas sem backups. Lembre-se de que apenas os backups automáticos são baixados; os demais arquivos são ignorados.
- Backups baixados sem o respectivo arquivo de registro.
- Cursos no arquivo especificado em --file que não foram encontrados, ou cursos encontrados, mas fora do intervalo de datas.
- Se o script foi interrompido antes do esperado e quantos cursos não foram processados
Exemplos
Baixando uma lista de cursos em um arquivo
python3 auto_archive_bulk_download.py --site https://mysite.blackboard.com
-- key <application key> --output ~/Downloads/autoArchives
--file ~/Documents/feedFile.txt
Esse modo requer um feed-file. O script processa um arquivo com uma lista de Course IDs e baixará os backups desses cursos.
O feed-file é um arquivo de texto simples com os IDs dos cursos a serem baixados. Um ID de curso por linha, sem nenhuma outra informação, delimitador ou cabeçalho. Por exemplo,
2021-ENG001 2021-ENG002 2020-MAT005
É importante usar o Course_ID, e não outros valores.
Baixando cursos criados entre datas
python3 auto_archive_bulk_download.py --site https://mysite.blackboard.com
-- key <application key> --output ~/Downloads/autoArchives
--beginDate 2020/01/20 --endDate 2021/01/20
Baixando para buckets S3
O script pode ser utilizado de modo que, em vez de baixar para um diretório local, os arquivos sejam carregados diretamente para um bucket S3. Você precisará criar um bucket e uma chave de acesso com permissões suficientes para carregar arquivos.
Para poder usar o bucket:
- É necessário exportar a AWS Access Key ID e a Secret key como variáveis de ambiente utilizando os nomes padrão da AWS.
- O path do bucket é indicado com a notação padrão do S3 em vez do path local. Exemplo: s3://mybucket/myfolder/
- A barra no final do endereço do bucket é importante; não a omita.
Lembre-se de executar uma única instância do script para evitar a degradação do desempenho do servidor.
Limitações
Lembre-se de que os aplicativos REST API têm um limite de 10.000 chamadas diárias. Esse script usa uma chamada por curso, além de algumas outras para encontrar as pastas; portanto, em um dia podem ser baixados cerca de 9.900 cursos, se as chamadas não forem usadas para mais nada. Se o limite for atingido, o script será interrompido, indicará quantos cursos não foram processados e exibirá o código 1. Aqui você pode ver como aumentar o limite de solicitações da API.
Comentários
0 comentários
iniciar sessão para comentar.