文档 API参考

使用增量导出API

你可以使用增量导出API获取自上次请求以来在Zendesk Support中更改或创建的项目。亚博它是这样工作的:

  • 下午5点申请“把今天中午以来所有改签的票都给我。”
  • 响应这是从中午到下午5点(包括下午5点)换过的票。
  • 晚上7点申请“把下午5点以后换过的票给我。”
  • 响应这是从下午5点到7点(包括7点)换过的票。

增量导出工作流

最初使用API从某个任意里程碑导出项目的完整列表，然后定期轮询API以增量导出自上次轮询以来添加或更改的项目。您不应该使用此API重复导出完整的数据集。

工作流程如下:

  1. 为第一个计划导出定义开始时间。

    API将返回在开始时间时或之后创建或更改的所有项。

    这是一次性的要求。

  2. 导出项目。

    的增量票务出口Endpoint支持两种导出方法:基于指针的和基于时间的。其他端点只支持基于时间的导出。

    请注意:这些方法不同于其他端点中使用的游标分页方法。

    如果你想用基于指针的增量导出对于门票(推荐)，使用以下API路径:

    GET / api / v2 /增量/ / cursor.json票吗?start_time = {unix_time}

    使用基于游标的增量导出，每页结果都包含一个游标指针，用作下一页或下一个导出的起点。您不需要为下一页或导出提供开始时间，而且API也不提供。

    在可能的情况下，强烈建议选择基于游标的导出。游标分页提供更一致的性能和响应体大小。

    如果你选择基于时间的增量出口，使用以下API路径进行初始导出:

    GET / api / v2 /增量/ tickets.json吗?start_time = {unix_time}

    使用基于时间的增量导出，每个页面都包含一个结束时间，用作下一页或下一个导出的开始时间。它不提供游标指针。

    在任何一种导出方法中，都要读取end_of_stream每个页面上的布尔值，以确定何时到达最后一页结果。如果这是真的，那就已经是最后一页了。

  3. 根据导出方法，保存光标指针或最后一页结果中指定的结束时间。

  4. 在下一次计划导出时，检索保存的游标指针或结束时间。

  5. 使用游标指针或结束时间作为导出的起始点。

    例如，下面的导出使用前一个导出的最后一个游标值作为起始点:

    GET / api / v2 /增量/ / cursor.json票吗?光标= MTU4MDc1Mzc5OC4wfHw0MzJ8

    下面的导出使用前一个导出的结束时间作为起始点:

    GET / api / v2 /增量/ tickets.json吗?start_time = 1568330298

  6. 对后续的导出重复步骤3到步骤5。

    为了防止竞争条件，票证和票证事件导出端点将不返回最近一分钟的数据。在基于时间的导出中，返回end_time财产(或start_time的参数。next_pageURL)永远不会超过一分钟前。

基于指针的增量导出

在基于光标的增量导出中，每页结果都包含一个“after”光标指针，用作下一页结果的起始光标。当所有结果都返回后，将after光标指针保存在最后一页上，并将其用作下一个导出的起始光标。

基于指针的增量导出目前仅支持以下类型票．强烈建议使用这种方法处理票据，因为它提供了更一致的性能和响应体大小。

为初始请求使用以下路径:

GET / api / v2 /增量/ / cursor.json票吗?start_time = {unix_time}

在使用start_time参数，则使用光标参数用于所有后续结果页面以及所有后续导出:

GET / api / v2 /增量/ / cursor.json票吗?光标= {cursor_pointer}

控件中包含游标指针after_cursor财产以及在after_url属性:

             

              
{“门票”：［…]，“after_url”：“https://example.亚博zendesk.com/api/v2/incremental/tickets/cursor.json?cursor=MTU4MDc1Mzc5OC4wfHw0MzJ8”，“after_cursor”：“MTU4MDc1Mzc5OC4wfHw0MzJ8”，…“end_of_stream”：假}

使用end_of_stream属性确定何时停止分页。如果end_of_stream为false，则继续使用after_cursor(或after_urlURL)以获得下一页的结果。如果end_of_stream是真的，结果已经到了最后一页。停止分页并保存after_cursor指针(或after_urlURL)用于下次导出。

在下次导出中，使用您保存的光标指针从您离开的位置重新开始。在前面的示例中，after_cursor结果最后一页的指针为“MTU4MDc1Mzc5OC4wfHw0MzJ8”。用光标指针开始下一个导出:

GET / api / v2 /增量/ / cursor.json票吗?光标= MTU4MDc1Mzc5OC4wfHw0MzJ8

基于时间的增量出口

在基于时间的增量导出中，每页结果都包含一个结束时间，用作下一页结果的开始时间。返回所有结果后，保存最后一页的结束时间，并将其用作下一次导出的开始时间。

所有增量导出端点都支持基于时间的导出。

初始请求的路径如下所示:

GET / api / v2 /增量/{物品}. json吗?start_time = {unix_time}

这些项可以是票证、票证事件、用户、组织等等。

初始请求之后，继续使用start_time参数获取后续页。参数指定下一个开始时间值end_time财产以及next_page每个结果页面包含的URL:

             

              
{“门票”：［…]，“next_page”：“https://example.亚博zendesk.com/api/v2/incremental/tickets.json?start_time=1542953046”，“end_time”：1542953046，…“end_of_stream”：假}

这两种情况中的时间1542953046都等于generated_timestamp页面中最后一项的时间。

由于基于时间的分页的限制，后续响应可能包含重复项。看到排除重复项目了解更多信息。

使用end_of_stream属性确定何时停止分页。如果end_of_stream为false，则继续使用end_time(或next_pageURL)以获得下一页的结果。如果end_of_stream为true时，停止分页并保存end_time值(或next_pageURL)用于下一次计划的导出。

在您的下一个导出中，使用您节省的时间从您离开的地方重新开始。在前面的示例中，end_time结果最后一页的值为“1542953046”。您将使用以下值开始下一个计划导出:

GET / api / v2 /增量/ tickets.json吗?start_time = 1542953046

请注意:基于时间的分页包括数属性，但不应将其用作检测最后一页结果的方法。在正常情况下，这些端点每页最多返回1000个条目，但并非总是如此。如果项目共享相同的时间戳，则可能超过1000个项目的限制。因此，数不是完整性的可靠指标。相反,使用end_of_stream确定何时停止分页。

基于时间的导出的轮询策略

基于时间的增量导出不能防止由覆盖重叠时间段的请求引起的重复。每个查询都可以归结为搜索在您的日期之后或之后更新的项目start_time价值。如果每个请求的开始时间早于项被修改的时间，则同一项可以包含在多个导出中。

或者，如果在两者之间留下空白，则可能会遗漏记录end_time的前一个请求和start_time下一个。

为了防止请求之间的间隔，请使用最后一个end_time的值start_time下一个计划出口的。

排除重复项目

由于基于时间的分页的限制，导出的数据可能包含重复的项。

在获得所有结果后，您可以通过过滤掉与前一个项目共享以下属性值的任何项目来排除重复的项目:

出口 过滤值
票 id+updated_at
票事件 id+created_at
用户 id+updated_at
组织 id+updated_at

基于时间的导出包含重复项，以防止同时更新或创建的项在页面末尾被跳过。例如，假设per_page参数为50，同时更新数据集中的3张票。如果三张票中的第一张在第1页的位置50，那么第2页的开始时间将被设置为返回在第1页最后一张票之后创建或更新的票。如果最后一张票没有转到下一页，就会跳过两张票。

出口的票

使用增量票务出口端点用于导出自上次请求以来创建或更新的票据。

您可以使用基于游标的导出或基于时间的导出来导出票据。亚博Zendesk建议使用基于光标的导出。看到基于指针的增量导出．

若要使用基于时间的导出，请参见基于时间的增量出口．

不包括删除的票

删除的票据仍然出现在导出中，因为票据记录仍然存在。亚博Zendesk会在删除后30天内删除用户提供的信息，如果是手动永久删除，则会立即删除用户提供的信息。

当票据被擦除时，会发生以下情况:

  • 主题和描述被替换为“擦洗”。
  • 文本、下拉、多选择和日期字段中的信息将被替换为X
  • 数值字段值被替换为0
  • 没有值的字段为空

您可以在获得所有结果后，通过过滤掉任何带有a的门票来排除这些门票状态“删除”。

请注意Ze亚博ndesk于2016年10月16日开始清理被删除的门票。

不包括系统更新的票证(基于时间的出口)

增量票证导出可以返回由于与正常业务过程中发生的票证事件无关的原因而由系统更新的票证。这种系统更新的一个例子是Zendesk的数据库回填。亚博

您可以在获得结果后，通过过滤掉任何带有updated_at时间早于start_time时间。

这条规则的推理如下。的updated_at属性不用于记录系统更新。系统更新由generated_timestamp属性(所有其他票证更新也是如此)。的updated_at属性仅用于生成已定义的票事件．因此，仅由系统更新的结果中的任何票证都将具有generated_timestamp那是晚于start_time但是一个updated_at时间早于start_time．

基于指针的增量导出没有start_time为了与updated_at售票时间。

导出门票事件

使用增量票务事件导出端点，用于导出自上次请求以来票据上发生的事件。每个事件都绑定到票据上的更新，并包含在该更改中更新的所有字段。

票据事件只支持基于时间的导出。看到基于时间的增量出口．

理解响应中的旧票据事件

票证事件不随时间变化，因此它们通常以更新的时间戳出现。然而，在某些情况下，系统可能会在事后更改事件，通常是在票据存档和删除时。因此，API可能会返回在请求之前发生的事件start_time时间。

属性返回记录generated_timestamp时间戳，而不是updated_at时间戳。当门票存档时，整个事件历史记录移动到generated_timestamp关闭的时间戳。当存档的票据被删除时，整个事件历史记录将移动到generated_timestamp删除时间戳。

例如，开始时间为2019年1月1日的请求可能会返回2014年的票证事件，因为长期存档的票证最近被删除了。

注意，事件对象没有generated_timestamp财产。