Quando si crea un'integrazione dati automatizzata con Canvas, è consigliabile esercitarsi a utilizzare l'API per importare i dati SIS in Canvas. Un metodo per utilizzare un'API è tramite cURL, uno strumento da riga di comando per il trasferimento dati supportato su tutti i sistemi operativi (Windows, Linux e OSX). In questa lezione, gli esempi dovrebbero funzionare con Windows 7+, Windows Server 2003+, Ubuntu 12+ (Desktop/Server) e OSX Mountain Lion+.
Gli esempi in questa lezione sono forniti per aiutarti a imparare come esercitarti nell'uso dell'API per importare contenuti in Canvas tramite importazioni SIS.
Installa cURL
Assicurati che cURL sia installato correttamente sul tuo computer o sistema operativo.
OS X e Linux (Ubuntu)
cURL dovrebbe essere già installato ed eseguito dall'applicazione Terminale .
cURL potrebbe essere già installato. Se non è già installato, esegui il seguente comando con un utente con privilegi sudo:
sudo apt-get install curl
Dopo aver installato cURL, testare l'installazione digitando il seguente comando su un terminale o un prompt dei comandi:
curl --version
Se l'installazione è avvenuta correttamente, dovrebbe essere visualizzata la versione di cURL.
Finestre
Se prevedi di utilizzare Windows come server di importazione, dovresti valutare l'utilizzo di PowerShell anziché cURL per il tuo strumento di importazione di produzione. PowerShell è nativo di Windows e dovrebbe generare uno script di importazione più affidabile rispetto all'utilizzo di cURL e di un file batch. Consigliamo di utilizzare cURL su Windows solo a scopo di test. Scopri come installare PowerShell su Windows.
Importa file di prova
Esercitatevi a usare l'API prima di aggiungere complessità a uno script.
- Nella directory "tmp", crea un file CSV denominato \P\P\P\P che creerà un corso base. Il nome del file fa distinzione tra maiuscole e minuscole. In alternativa, puoi anche usare questo file di esempio: test_course.csv
- Aprire un prompt dei comandi del terminale e cambiare directory nella directory "tmp".
- Esegui il comando seguente sostituendo <api_token> con il token API creato in precedenza e <canvas_fqdn> con il nome di dominio che utilizzi per accedere a Canvas (ad esempio: 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'
In caso di successo, dovresti ricevere una stringa JSON dal server che indica che l'importazione è stata creata e fornisce un ID per il processo di importazione. Il JSON avrà un aspetto simile a questo:
{"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"}}I parametri "id" e "workflow_state" sono informazioni importanti da conoscere durante lo sviluppo dello script. La loro assenza o il loro valore potrebbero indicare un problema. Se non hai ricevuto un parametro "id" o il valore "workflow_state" Se il tag è diverso da created , sarà necessario risolvere il problema prima di procedere.
Note:
- Una volta completato questo comando, sarà necessario il parametro "id" per verificare lo stato di un'importazione.
- Quando si importano file CSV di sezione, i valori
integration_id esistenti vengono ora mantenuti se la colonna integration_id non è inclusa nel file di importazione. Per rimuovere un integration_id , è necessario annullarne esplicitamente l'impostazione tramite il file change_sis_id.csv .
Controlla lo stato dell'importazione
Una parte importante del processo di importazione automatizzata è conoscere lo stato dell'importazione precedente prima di elaborare quella successiva.
Se si decide di eseguire un'importazione standard, è necessario correggere l'importazione precedente prima di elaborare quella successiva, poiché le informazioni potrebbero andare perse a causa del processo di importazione non riuscito/incompleto. Se si utilizzano importazioni batch complete, lo stato è comunque importante perché non si desidera avviare il batch completo successivo finché il batch precedente non è terminato. A seconda della frequenza di aggiornamento, delle dimensioni dell'importazione e di altri fattori, un'importazione batch completa potrebbe facilmente superare la finestra temporale.
Eseguire il seguente comando con queste sostituzioni:
- Sostituisci <api_token> con il token API creato in precedenza
- Sostituisci <canvas_fqdn> con il tuo dominio Canvas
- Sostituisci <import_id> con l'ID del tuo file di test importato
curl -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'
Il comando dovrebbe restituire una risposta JSON contenente lo stato e il risultato se l'importazione è completa. Di seguito è riportato un esempio del risultato ottenuto eseguendo il comando precedente:
{"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}}}Ecco alcuni punti chiave da considerare riguardo ai risultati JSON:
Progresso : in un processo in esecuzione, il parametro "Progresso" indica la percentuale di completamento del processo. Al termine dell'esecuzione di un processo, l'avanzamento sarà pari al 100%.
workflow_state : il parametro "workflow_state" indica lo stato corrente di un processo in esecuzione. Nella maggior parte dei casi, un processo completato correttamente indicherà lo stato "importato". Se viene visualizzato un valore diverso da "importato" o "importazione in corso", è necessario fermarsi qui e risolvere il problema prima di procedere.
- Se lo stato è "importing", provare a eseguire nuovamente il comando finché lo stato non restituisce "imported".
- Se lo stato è "imported_with_messages" o "failed_with_messages", controlla il contenuto di "processing_warnings" o "processing_errors".