我如何练习使用API将数据导入到Canvas账户？

[#1]

当使用Canvas来创建自动化数据整合时，您应该练习使用API将数据导入到Canvas。 一种使用API的方法是通过cURL，它是一种得到所有运作系统支持（Windows、Linux和OSX）用于转移数据的指令行工具。在本教程，例子应该可对Windows 7+、Windows Server 2003+、Ubuntu 12+（桌面电脑/服务器）和OSX Mountain Lion+。

本教程的例子会对您提供帮助了解如何使用SIS导入来练习使用API将内容导入到Canvas。

确认已安装了cURL

在您的电脑或运作系统，确认cURL已经被正确地安装到您的电脑或运作系统。

OS X 和 Linus (Ubuntu)

cURL应该已经安装，从终端应用程序运行。

cURL可能已经安装。 如果还未安装，使用具备sudo的权限用户，运行以下命令：

sudo apt-get install curl

安装cURL后，在终端或命令提示符键入以下，测试安装情况：

curl --version

如果安装成功，cURL的版本将会显示。

Windows

如果您准备使用Windows作为您的导入服务器，您应该考虑使用PowerShell，而不是使用cURL作于生产导入的工具。 PowerShell是原产于Windows，所以应该比使用cURL和批量文件更可靠充当导入脚本。 只为测试目的，我们建议在Windows使用cURL。

• 了解如何在Windows安装cURL。

导入测试文件

在添加脚本的复杂性前，练习使用API。

1. 在“tmp”目录，创建将可以创建基本课程的CSV文件名。文件名是区分大小写的。或您也可以使用这个示例文件：test_course.csv
2. 打开终端命令提示，并改变目录到“tmp”目录。
3. 运行以下命令，更换<api_token>与您之前创建的API令牌，和<canvas_fqdn>您访问Canvas的域名（例如：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'

成功时，您应该会收到一条JSON发自服务器表示导入已经被创建，并提供导入工作的ID。 JSON看起来像：

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

“ID”和“workflow_state”参数是当您发展您的脚本时必须要知道的重要信息。 他们的缺席或价值可能会表明问题。如果您得到“id”参数或"workflow_state“标签与创建的不同，您将需要在继续之前排除故障，找出原因。

注意：当此命令完成时，您将要验证”id“的参数导入状态。

验证导入状态

自动导入过程的一个重要部分是在处理您的导入之前知道您先前的导入状态。

如果您决定运行标准导入，您必须在处理下一个导入之前修复先前的导入，因为资料可能会从失败/未完成的导入中失去。 如果您使用全批量导入，状态还是重要的因为您不想开始下一个全批量直到先前的批量已完成。 取决于您的更新频率、导入的大小和其它因素，全批量导入可以容易地侵占您的时间窗口。

运行并更换以下命令：

• 更换<api_token>与先前创建的API令牌
• 更换<canvas_fqdn>与您的Canvas域名
• 更换 <import_id>与从您的测试文件导入的ID

curl -H "Authorization: Bearer <api_token>" 'https://<canvas_fqdn>/api/v1/accounts/self/sis_imports/<import_id>'

如果导入完成，命令应该会回到一个包含状态和结果的JSON对应。 以下是一个在上个步骤运行命令的结果：

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

这是几个重点考虑有关JSON的结果：

进度（progress）：在一个运行工作钟，”进度“参数表示工作完成的百分率。 当工作完成时，进度将是百分百。

workflow_state:”workflow_state“参数表示正运行工作的目前状态。 在大部分案例，成功完成的工作将使用”imported“状态表示。 如果您看见其它状态，而不是”imported“或”importing“，您需要在继续之前必须暂停并找出故障的原因。

• 如果状态是”importing“，再尝试运行命令直到回报”imported“状态。
• 如果状态是”imported_with_messages“或”failed_with_messages“，检查”processing_warnings“或”processing_error“的内容。