Ao criar uma integração de dados automatizada com o Canvas, você deve praticar o uso da API para importar dados do SIS para o Canvas. Um método para usar a API é por meio do cURL, uma ferramenta de linha de comando para transferência de dados compatível com todos os sistemas operacionais (Windows, Linux e OSX). Nesta lição, os exemplos devem funcionar com Windows 7+, Windows Server 2003+, Ubuntu 12+ (Desktop/Server) e OSX Mountain Lion+.
Os exemplos desta lição são fornecidos para ajudá-lo a praticar o uso da API para importar conteúdo para o Canvas usando importações do SIS.
Instale o cURL
No seu computador ou sistema operacional, certifique-se de que o cURL esteja instalado corretamente.
OS X e Linux (Ubuntu)
O cURL já deve estar instalado e pronto para ser executado a partir do aplicativo Terminal .
O cURL pode já estar instalado. Caso contrário, execute o seguinte comando com um usuário que tenha privilégios de sudo:
sudo apt-get install curl
Após instalar o cURL, teste a instalação digitando o seguinte comando em um terminal ou prompt de comando:
curl --version
Se a instalação for bem-sucedida, a versão do cURL deverá ser exibida.
Windows
Se você planeja usar o Windows como servidor de importação, considere usar o PowerShell em vez do cURL como ferramenta de importação para produção. O PowerShell é nativo do Windows e deve resultar em um script de importação mais confiável do que o uso do cURL e de um arquivo em lote. Recomendamos o uso do cURL no Windows apenas para fins de teste. Saiba como instalar o PowerShell no Windows.
Importar arquivo de teste
Pratique o uso da API antes de adicionar a complexidade de um script.
- No diretório “tmp”, crie um arquivo CSV com o nome \P\P\P\P que criará um curso básico. O nome do arquivo diferencia maiúsculas de minúsculas. Ou, você também pode usar este arquivo de exemplo: test_course.csv
- Abra um terminal e acesse o diretório “tmp”.
- Execute o comando abaixo, substituindo <api_token> pelo token de API que você criou anteriormente e <canvas_fqdn> pelo nome de domínio que você usa para acessar o Canvas (exemplo: institution_name.test.instructure.com):
curl -F attachment=@test_course.csv -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports.json?import_type=instructure_csv'
Após a conclusão bem-sucedida, você deverá receber do servidor uma string JSON indicando que a importação foi criada e fornecendo um ID para a tarefa de importação. O JSON terá uma aparência semelhante a esta:
{"created_at":"2014-02-27T13:03:39Z","ended_at":null,"updated_at":"2014-02-27T13:03:39Z","progress":0,"id":6670997,"workflow_state":"created","data":{"import_type":"instructure_csv"}}Os parâmetros "id" e "workflow_state" são informações importantes para o desenvolvimento do seu script. A ausência ou o valor deles pode indicar um problema. Se você não tiver um parâmetro "id" ou se o seu parâmetro "workflow_state" estiver incorreto, você pode estar enfrentando um problema. Se a tag for diferente de "created" , você precisará solucionar o problema antes de prosseguir.
Notas:
- Quando este comando for concluído, você precisará do parâmetro "id" para verificar o status de uma importação.
- Ao importar arquivos CSV de seção, os valores existentes
integration_id agora são mantidos se a coluna integration_id não estiver incluída no arquivo de importação. Para remover um integration_id , ele deve ser explicitamente desativado usando o arquivo ` change_sis_id.csv .
Verificar status da importação
Uma parte importante do processo de importação automatizada é conhecer o status da importação anterior antes de processar a próxima.
Se optar por uma importação padrão, é essencial corrigir a importação anterior antes de processar a próxima, pois informações podem ser perdidas devido a uma importação com falha ou incompleta. Mesmo em importações em lote, o estado da importação continua sendo importante, pois o próximo lote só poderá ser iniciado após a conclusão do anterior. Dependendo da frequência de atualização, do tamanho da importação e de outros fatores, uma importação em lote completa pode facilmente ultrapassar o tempo disponível.
Execute o seguinte comando com estas substituições:
- Substitua <api_token> pelo token da API criado anteriormente.
- Substitua <canvas_fqdn> pelo seu domínio do Canvas.
- Substitua <import_id> pelo ID do seu arquivo de teste de importação.
curl -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'
O comando deve retornar uma resposta JSON contendo o status e o resultado caso a importação seja concluída. Segue um exemplo do resultado da execução do comando anterior:
{"created_at":"2014-02-27T13:03:39Z","ended_at":"2014-02-27T13:03:39Z","updated_at":"2014-02-27T13:03:39Z","progress":100,"id":6670997,"workflow_state":"imported","data":{"import_type":"instructure_csv","supplied_batches":["course"],"counts":{"accounts":0,"terms":0,"abstract_courses":0,"courses":1,"sections":0,"xlists":0,"users":0,"enrollments":0,"groups":0,"group_memberships":0,"grade_publishing_results":0}}}Aqui estão alguns pontos importantes a serem considerados em relação aos resultados JSON:
Progresso : Em uma tarefa em execução, o parâmetro "progresso" indica a porcentagem de conclusão da tarefa. Quando uma tarefa é finalizada, o progresso será de 100%.
workflow_state : O parâmetro "workflow_state" indica o estado atual de uma tarefa em execução. Na maioria dos casos, uma tarefa concluída com sucesso indicará o estado "importado". Se você vir qualquer coisa diferente de "importado" ou "importando", será necessário interromper o processo e solucionar o problema antes de prosseguir.
- Se o estado for "importando", tente executar o comando novamente até que o estado retorne "importado".
- Se o estado for "imported_with_messages" ou "failed_with_messages", verifique o conteúdo de "processing_warnings" ou "processing_errors".