本文档包含有关 Canvas Data 2 (CD2) 的一些常见技术问题。
查询结果集的“meta”字段中的时间戳“ts”是什么意思？
ts是表中记录的最后修改时间戳（或提交时间）。当一条新记录插入到 CD2 托管的表中时，系统会为其分配插入时间。当该记录稍后被更新时，时间戳会刷新以匹配更新发生的时间。最后，当记录最终被删除时，时间戳会反映删除时间。
结果集中的“since”和“until”与“ts”有何关系？
since和until是对提交时间（或最后修改时间戳）的筛选条件。结果集中的所有记录都在since和until的范围内。
结果集中是否存在键值相同的重复记录？
不；快照查询或增量查询结果集中的键始终是唯一的。
如何将增量查询结果集转换为 SQL 语句？
您可能需要使用 INSERT 或 UPDATE 语句。在 PostgreSQL 中，其形式如下：
INSERT INTO ... (...)
VALUES (...)
ON CONFLICT (...)
DO UPDATE SET ...
结果集中存在只有“键”而没有“值的”记录，我该如何处理？
输出记录中如果存在key字段但没有value字段，则对应于已删除的记录。这些数据在 Instructure 系统中已不再可用，您也应该从本地副本中删除这些数据。这些记录在元数据中也被标记为“D”。
'__cd2_oversized_truncated__' 是什么意思？（某些字段/列的值可能为 '__cd2_oversized_truncated__'。）
__cd2_oversized_truncated__是一个特殊的占位符（字符串常量），表示原始数据过大，无法包含在结果中，通常大小为几兆字节。遗憾的是，无法恢复这些字段/列的值。然而，如此大的值通常是由于错误造成的（例如，学生将二进制 Word 文档复制到纯文本字段中），很少包含对分析有用的有价值的信息。
如何获取数据库在某一时间点的状态？
CD2 不支持时间点查询，您无法重建数据库的先前历史状态，您只能将本地副本与 Instructure 保存的最新状态同步。
如何获取从创世之初到特定日期的所有数据？
遗憾的是，CD2 不支持此功能。CD2 允许您将本地数据库与 Instructure 的当前数据库状态同步。如果 Instructure 域中的源数据库中的某个记录已被更新或删除，您将无法检索该记录的先前版本。但是，只要记录存在于 Instructure 的系统中，它们就一直可用，不会随时间消失。例如，您应该能够获取学生申请的所有课程或提交的所有作业，因为它们都显示为不同的记录，而不是同一记录的不同版本。
如何获取所有记录转换的流？
CD2 允许您将数据库更新到最新状态，但无法（可靠地）返回中间状态。即使您尝试以较短的间隔轮询 CD2 API 查询作业端点，对同一记录的多个变更数据捕获事件也会合并为一个变更，并且增量查询结果集中只会返回该单个变更。CD2 的输出不能作为所有数据库转换的变更日志，而只能用于将本地数据库与 Instructure 系统中的最新状态保持同步。
故障排除
我收到的响应状态码是 HTTP 4xx。
HTTP 4xx 类错误（例如 HTTP 400 Bad Request）是永久性错误。要了解请求被拒绝的原因，请检查 HTTP 响应的有效负载。HTTP 响应体应为application/json媒体类型，并包含一个带有error属性的对象。该对象包含有关请求被拒绝原因的信息。
增量查询的meta中包含一个名为action字段，用于指定记录是被插入（或更新）还是被删除。如果记录被插入，通常需要在数据库中使用 INSERT 或 UPDATE SQL 语句来更新该记录。如果记录被删除，则需要使用 DELETE SQL 语句来删除该记录。
快照查询没有action ，因为这是一个冗余字段。快照查询假定数据库为空，所有记录都将被插入。通常情况下，您会使用 COPY 或 INSERT 语句来填充数据库。
CD2 中的 CSV 输出符合RFC 4180 标准。该规范的 2.6 节讨论了值中换行符的表示方式，但工具通常未能正确实现。具体来说，如果值中包含嵌入式换行符，则输出应使用双引号括起来，但换行符本身应按原样表示（而不是使用转义序列）。然而，工具通常假定记录始终只占一行，但这在上述情况下并不成立。
PostgreSQL 创建脚本示例中使用了“CREATE TYPE ... AS (...)”，但我的数据仓库或数据库引擎不支持这种语法。
用于创建数据库的 PostgreSQL 参考脚本使用了所谓的嵌套类型。并非所有数据库引擎都支持嵌套类型。如果您的引擎不支持嵌套类型，您可以使用更通用的 SQL 类型json. json允许您将任意嵌套结构作为 JSON 数据插入。但是，您可能无法像对其他列类型那样有效地对json列进行筛选。
我收到一个错误提示，说没有该范围的数据，或者范围超出了边界。
请确保正确链接增量查询。您应该始终使用前一个增量查询的until时间戳（或初始快照查询的at时间戳）作为下一个增量查询的since时间戳。您不应该为这些参数指定任意值，而应该仅重用先前响应返回的值。
看来我必须同时提供“自……起”时间戳才能提供“直到”时间戳。
时间戳 ` since`和 ` until`用于链接增量查询。您应该始终使用前一个增量查询的`until`时间戳作为下一个增量查询的`since`时间戳。CD2 仅存储任何记录的最新状态， `until`不能用于重建记录在过去某个时间点的状态。
CD2 API 返回的文件集中缺少一些部件号或序列号。
CD2 API 可能会返回序列号不连续的 S3 对象，例如，可能存在part1 、 part2和part5 ，但缺少part3和part4 。这并非错误。
文件名通常包含一些信息。你不应该根据文件名模式做出任何假设。
CD2 API 返回的文件是由多个独立执行的并发任务生成的。根据执行上下文、输入参数等因素，一个任务可能会找到多条与查询匹配的记录，也可能找不到任何记录。此外，任务在处理记录的过程中可能会被终止，其工作负载可能会被分配给另一个任务。因此，文件编号可能不连续，这就解释了为什么您可能会看到part1和part5 ，但没有part4 。
CD2 API 生成的每个输出文件可能包含零条或多条记录。集成脚本应能处理文件不包含任何记录的情况。
CD2 API 返回的文件是由独立执行的并发任务生成的。根据执行上下文、输入参数等因素，一个任务可能会找到多条与查询匹配的记录，也可能找不到任何记录。如果没有匹配的记录，则返回一个空文件。
官方 CD2 客户端库会自动处理空文件。