Como pratico o uso da API para importar dados SIS para uma conta do Canvas?

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 de usar uma API é por meio de cURL, uma ferramenta de linha de comando para transferência de dados com suporte em todos os sistemas operacionais (Windows, Linux e OSX). Nesta lição, os exemplos devem funcionar com Windows 7 ou superior, Windows Server 2003+, Ubuntu 12+ (Desktop/Servidor) e OSX Mountain Lion+.

Os exemplos nesta lição são fornecidos para ajudá-lo a aprender como praticar o uso da API para importar conteúdo para o Canvas usando importações SIS.

Instalar cURL

Em seu computador ou sistema operacional, certifique-se de que cURL esteja instalado corretamente em seu computador ou sistema operacional.

OS X & Linux (Ubuntu)

O cURL já deve estar instalado e executado a partir do aplicativo Terminal.

O cURL pode já estar instalado. Se ainda não estiver instalado, execute o seguinte comando com um usuário que tenha privilégios sudo:

sudo apt-get install curl

Depois de instalar o cURL, teste a instalação digitando o seguinte comando em um terminal ou prompt de comando:

curl --versão

Se instalado com sucesso, a versão do cURL deve ser exibida.

Windows

Se você está planejando usar o Windows como servidor de importação, deve considerar o uso do PowerShell em vez de cURL para sua ferramenta de importação de produção. O PowerShell é nativo do Windows e deve resultar em um script de importação mais confiável do que usar cURL e um arquivo em lote. Recomendamos o uso de cURL no Windows apenas para fins de teste. Aprenda a instalar o PowerShell no Windows.

Importar arquivo de teste

Pratique o uso da API antes de adicionar a complexidade de um script.

  1. No diretório “tmp”, crie um arquivo CSV com o nome \P\P\P\Pque 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
  2. Abra um prompt de comando do terminal e mude de diretório para o diretório “tmp”.
  3. Execute o comando abaixo substituindo <api_token> com o token de API que você criou anteriormente e <canvas_fqdn> com o nome de domínio que você usa para acessar o Canvas (exemplo: nome_instituição.teste.instructure.com):
curl -F attachment=@test_course.csv -H "Autorização: Portador <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports.json?import_type=instructure_csv'

Em caso de sucesso, você deve receber uma sequência de JSON de volta do servidor que indica que a importação foi criada e fornece um ID para o trabalho de importação. O JSON será semelhante a:

{"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 que você deve conhecer à medida que desenvolve seu script. Sua ausência ou valor pode indicar um problema. Se você não obteve um parâmetro "id" ou se sua tag "workflow_state" não foi criada, você precisará solucionar a causa antes de prosseguir.

Nota: Quando este comando for concluído, você precisará do parâmetro "id" para verificar o status de uma importação.

Verificar o status de importação

Uma parte importante do processo de importação automatizada é saber o status de sua importação anterior antes de processar sua próxima importação.

Se você decidir fazer uma importação padrão, deverá corrigir a importação anterior antes de processar sua próxima importação, pois as informações podem ser perdidas do trabalho de importação com falha/incompleto. Se você estiver usando importações de lote completo, o estado ainda é importante porque você não deseja iniciar o próximo lote completo até que o lote anterior seja concluído. Dependendo de sua frequência de atualização, tamanho da importação e outros fatores, uma importação de lote completo pode facilmente ultrapassar sua janela de tempo.

Execute o seguinte comando com estas substituições:

  • Substitua <api_token> com o token de API criado anteriormente
  • Substitua <canvas_fqdn> com o seu domínio do Canvas
  • Substitua <import_id> com o ID de sua importação de arquivo de teste
curl -H "Autorização: Portador <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'

O comando deve retornar uma resposta JSON que contém o status e o resultado se a importação for concluída. A seguir está um exemplo de resultado do comando executado na etapa 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-chave a serem considerados em relação aos resultados JSON:

progresso: Em um trabalho em execução, o parâmetro "progresso" indica a porcentagem concluída para o trabalho. Quando um trabalho é executado em execução, o progresso será de 100 por cento.

workflow_state: O parâmetro "workflow_state" indica o estado atual de um trabalho em execução. Na maioria dos casos, um trabalho concluído com sucesso indicará um estado de "imported." Se você vir algo diferente de "imported" ou "importing," você precisará parar aqui e solucionar a causa antes de continuar.

  • Se o estado for "importing," tente executar o comando novamente até que o estado retorne "imported".
  • Se o estado for "imported_with_messages" ou "failed_with_messages," marque os conteúdos do "processing_warnings" ou "processing_errors".