¿Cómo practico usar la API para importar los datos de SIS en una cuenta de Canvas?

Al crear una integración de datos automatizada con Canvas, debe practicar usando la API para importar los datos de SIS en Canvas. Un método para usar una API es a través de cURL, una herramienta de línea de comando para transferir datos que se admite en todos los sistemas operativos (Windows, Linux y OSX). En esta lección, los ejemplos deben funcionar con Windows 7+, Windows Server 2003+, Ubuntu 12+ (escritorio/Servidor) y OSX Mountain Lion+.

Los ejemplos en esta lección se proporcionan para ayudarlo a aprender cómo practicar usar la API para importan el contenido en Canvas mediante el uso de importaciones de SIS.

Instalar cURL

En su computadora o sistema operativo, asegúrese de que cURL esté instalado correctamente en su computadora o sistema operativo.

OS X y Linux (Ubuntu)

cURL ya debe estar instalado y ejecutándose desde la aplicación Terminal.

cURL ya puede estar instalado. Si no está instalado, ejecute el siguiente comando con un usuario que tenga privilegios de Sudo:

sudo apt-get install curl

Después de instalar cURL, pruebe la instalación al ingresar el siguiente comando en un terminal o indicación de comando:

curl --version

Si está correctamente instalada, la versión de cURL debe aparecer.

Windows

Si está planificando usar Windows como su servidor de importación, debe considerar usar PowerShell en vez de cURL para su herramienta de importación de producción. PowerShell es nativo para Windows y debe resultar en un script de importación más confiable que usar cURL y un archivo de lote. Solamente recomendamos usar cURL en Windows para los fines de la prueba. Aprenda cómo instalar PowerShell en Windows.

Importar archivo de prueba

Practique usar la API ante de agregar la complejidad de un script.

  1. En el directorio “tmp”, cree un archivo CSV de nombre \P\P\P\P que creará un curso básico. El nombre del archivo distingue mayúsculas de minúsculas. O puede también usar este archivo de ejemplo: test_course.csv
  2. Abra una indicación de comando temporal y cambie el directorio en el directorio “tmp”.
  3. Ejecute el comando a continuación reemplazando <api_token> con el autentificador de API que creó anteriormente y <canvas_fqdn> con el nombre de dominio que usa para acceder a Canvas (ejemplo: 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'

Una vez que tenga éxito, debería recibir una secuencia de JSON nuevamente desde el servidor que indica que la importación se ha creado y ofrece una identificación para el trabajo de importación. El JSON se verá más o menos así:

{"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"}}

Los parámetros "id" y "workflow_state" representan información importante que debe conocer para desarrollar su script. Su ausencia o valor podría indicar un problema. Si no obtuvo un parámetro "id", o su etiqueta "workflow_state" no es creado (created), tendrá que resolver la causa antes de continuar.

Nota: Cuando este comando se complete, necesitará que el parámetro "id" verifique el estado de una importación.

Verificar el estado de la importación

Una parte importante del proceso de importación automatizado es saber el estado de su importación previa antes de procesar su próxima importación.

Si decide hacer una importación estándar, debe arreglar la importación previa antes de procesar su próxima importación porque la información puede faltar en el trabajo de importación fallido/incompleto. Si está usando las importaciones de lote completo, el estado aún es importante porque no desea comenzar su lote completo siguiente hasta que el lote anterior haya terminado. Según su frecuencia de actualización, tamaño de importación y otros factores, una importación de lote completo podría sobrepasar fácilmente su ventana de tiempo.

Ejecute el siguiente comando con estos reemplazos:

  • Reemplace <api_token> con el autentificador de API creado anteriormente
  • Reemplace <canvas_fqdn> con su dominio de Canvas
  • Reemplace <import_id> con la identificación de su importación de archivos más reciente
curl -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'

El comando debe devolver la respuesta JSON que contenga el estado y el resultado si la información está completa. El siguiente es un ejemplo del resultado de la ejecución del comando del paso 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}}}

Estos son algunos puntos clave a considerar con respecto a los resultados de JSON:

progress: En un trabajo en ejecución, el parámetro "progress" indica el porcentaje completo para el trabajo. Cuando un trabajo ya no se esté ejecutando, el progreso estará al 100 por ciento.

workflow_state: El parámetro "workflow_state" indica el estado actual de un trabajo en curso. En la mayoría de los cursos, un trabajo correctamente completado indicará un estado de "imported". Si ve cualquier cosa que no sea "imported" o "importing", tendrá que detenerse aquí y resolver la causa del problema antes de proseguir.

  • Si el estado es "importing", intente ejecutar el comando nuevamente hasta que el estado vuelva a "imported".
  • Si el estado es "imported_with_messages" o "failed_with_messages", verifique los contenidos de "processing_warnings" o "processing_errors".