Al crear una integración de datos automatizada con Canvas, debería practicar el uso de la API para importar datos SIS a Canvas. Un método para usar una API es mediante cURL, una herramienta de línea de comandos para transferir datos compatible con todos los sistemas operativos (Windows, Linux y OS X). En esta lección, los ejemplos deberían funcionar con Windows 7 o superior, Windows Server 2003 o superior, Ubuntu 12 o superior (Escritorio/Servidor) y OS X Mountain Lion o superior.
Los ejemplos de esta lección se proporcionan para ayudarlo a aprender a practicar el uso de la API para importar contenido a Canvas mediante importaciones 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 debería estar instalado y ejecutándose desde la aplicación Terminal .
Es posible que cURL ya esté instalado. Si no lo está, ejecute el siguiente comando con un usuario con privilegios de sudo:
sudo apt-get install curl
Después de instalar cURL, pruebe la instalación escribiendo el siguiente comando en una terminal o en el símbolo del sistema:
curl --version
Si se instala correctamente, debería mostrarse la versión de cURL.
Ventanas
Si planea usar Windows como servidor de importación, considere usar PowerShell en lugar de cURL como herramienta de importación de producción. PowerShell es nativo de Windows y debería generar un script de importación más confiable que usar cURL y un archivo por lotes. Solo recomendamos usar cURL en Windows para realizar pruebas. Aprenda a instalar PowerShell en Windows.
Importar archivo de prueba
Practique el uso de la API antes de agregar la complejidad de un script.
- En el directorio "tmp", cree un archivo CSV llamado \P\P\P\P que creará un curso básico. El nombre del archivo distingue entre mayúsculas y minúsculas. También puede usar este archivo de ejemplo: test_course.csv
- Abra un símbolo del sistema en la terminal y cambie el directorio al directorio “tmp”.
- Ejecute el siguiente comando reemplazando <api_token> con el token 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'
Si la importación se ha realizado correctamente, debería recibir una cadena JSON del servidor que indica que se ha creado y proporciona un ID para el trabajo de importación. El JSON tendrá un aspecto similar a este:
{"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" son información importante que debes conocer al desarrollar tu script. Su ausencia o valor podría indicar un problema. Si no tienes un parámetro "id" o tu "workflow_state" Si la etiqueta es algo distinto a created , deberá solucionar la causa antes de continuar.
Notas:
- Cuando se complete este comando, necesitará el parámetro "id" para verificar el estado de una importación.
- Al importar archivos CSV de sección, los valores
integration_id existentes se conservan si la columna integration_id no está incluida en el archivo de importación. Para eliminar un integration_id , debe anularse explícitamente mediante el archivo change_sis_id.csv .
Comprobar el estado de la importación
Una parte importante del proceso de importación automatizado es conocer el estado de su importación anterior antes de procesar su próxima importación.
Si decide realizar una importación estándar, debe corregir la importación anterior antes de procesar la siguiente, ya que podría perderse información del trabajo de importación fallido o incompleto. Si utiliza importaciones por lotes completos, el estado sigue siendo importante, ya que no desea iniciar el siguiente lote completo hasta que el anterior haya finalizado. Dependiendo de la frecuencia de actualización, el tamaño de la importación y otros factores, una importación por lotes completos podría fácilmente sobrepasar el tiempo límite.
Ejecute el siguiente comando con estos reemplazos:
- Reemplace <api_token> con el token de API creado anteriormente
- Reemplace <canvas_fqdn> con su dominio de Canvas
- Reemplace <import_id> con el ID de la importación de su archivo de prueba
curl -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'
El comando debe devolver una respuesta JSON que contenga el estado y el resultado si la importación se ha completado. A continuación, se muestra un ejemplo del resultado de ejecutar el 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}}}A continuación se presentan algunos puntos clave a tener en cuenta con respecto a los resultados JSON:
Progreso : En un trabajo en ejecución, el parámetro "progreso" indica el porcentaje de finalización del trabajo. Cuando un trabajo termina de ejecutarse, el progreso será del 100 %.
workflow_state : El parámetro "workflow_state" indica el estado actual de un trabajo en ejecución. En la mayoría de los casos, un trabajo completado correctamente indicará el estado "importado". Si ve algo distinto a "importado" o "importando", deberá detenerse aquí y solucionar el problema antes de continuar.
- Si el estado es "importando", intente ejecutar el comando nuevamente hasta que el estado regrese a "importado".
- Si el estado es "importado_con_mensajes" o "falló_con_mensajes", verifique el contenido de "advertencias_de_procesamiento" o "errores_de_procesamiento".