使用帮助中心API管理文章翻译
如果您计划定期将帮助中心的文章交付翻译，您可以通过使用帮助中心API来自动下载更新的文章并发送给本地化供应商。您还可以使用API上传本地化供应商返回的翻译。
免责声明: 亚博Zendesk提供本文仅用于教学目的。亚博Zendesk不支持或保证该代码。亚博Zendesk也不能为第三方技术提供支持，如Python或其库。
了解文章更新
本文描述如何下载已更新的文章<一个href="//www.ying8.net/developer/documentation/help_center/help-center-api/using-the-help-center-api/using-the-help-center-api-to-manage-article-translations/#option-2---downloading-articles-edited-after-a-start-time">开始时间之后或<一个href="//www.ying8.net/developer/documentation/help_center/help-center-api/using-the-help-center-api/using-the-help-center-api-to-manage-article-translations/#option-3---downloading-articles-edited-between-a-date-range">在日期范围之间送去翻译。这两种方法都依赖于本文updated_at财产。基本逻辑是检查每篇文章最后更新的时间，以确定需要翻译或重新翻译的文章。
然而，文章最后一次更新的时间和最后一次编辑的时间可能是不同的。的updated_at属性不仅记录文章最后一次编辑的时间，还记录其他文章更新的时间，例如有人向文章添加评论的时间。因此，有些文章即使“更新”了，也可能不需要翻译。
以发送文章为目的，对文章进行翻译edited_at时间是更好的衡量标准。的edited_at时间不仅反映正文或标题最后一次更新和发布的时间。如果文章还没有被编辑，它还会反映文章是什么时候创建的。
因此，本文还描述了如何根据它们筛选下载的文章edited_at财产。
选项1 -下载文章列表
下载文章的第一个选择是编译文章列表，然后用API下载每一篇文章。例如，当贡献者更新文章时，您可以让他们将文章添加到共享工作表或文档中的列表中。您还可以构建一个小型应用程序，将信息保存在轻量级数据库(如SQLite)中。这就是Zendesk文档团队用来下载文章进行交接的亚博方法。
使用<一个href="//www.ying8.net/developer/api-reference/help_center/help-center-api/articles/">显示文章端点下载每篇文章。端点按id下载特定的文章，看起来像这样:
https：//｛子域名}。亚博。com/api/v2/help_center/文章/｛article_id}。json
编写一个脚本或函数，在文章列表中循环或迭代，并向<一个href="//www.ying8.net/developer/api-reference/help_center/help-center-api/articles/">显示文章每篇文章的端点。
例子
下面的Python脚本遍历文章id列表并下载每篇文章。本例假设Zendesk帐户的子域名为“examp亚博le”(example.zendesk.com)。
进口json进口请求handoff_articles=(］article_list=(2342654，2432643］为article_id在article_list：url=f“https://example.亚博zendesk.com/api/v2/help_center/articles/ {article_id} . json”响应=请求。得到（url）。json（）article_content=｛“标题”：响应(“文章”］(“标题”］，“身体”：响应(“文章”］(“身体”］，“id”：article_id}handoff_articles。附加（article_content）与开放（“handoff_articles.json”，模式=' w '，编码=“utf - 8”）作为f：json。转储（handoff_articles，f，sort_keys=真正的，缩进=2）
它是如何工作的
脚本首先导入几个库。的json库是一个原生Python库，但是请求库单独安装。的<一个href="https://requests.readthedocs.io/en/latest/">请求库使处理HTTP请求更容易。看到<一个href="https://requests.readthedocs.io/en/latest/user/install/">安装说明。
该脚本设置一个为循环遍历文章id。它用每个id向Show Article端点发出API请求:
article_list=(2342654，2432643］为article_id在article_list：url=f“https://example.亚博zendesk.com/api/v2/help_center/articles/ {article_id} . json”响应=请求。得到（url）。json（）
API返回JSON数据。的json ()方法将返回的数据转换为Python数据类型，使其更易于使用。在这种情况下，数据被转换为一个字典，相当于Python中的JavaScript对象文字。
API返回的每个文章记录都包含关于该文章的各种数据。出于翻译的目的，你只需要文章的标题和正文。脚本将每篇文章的标题和正文打包，并将该包添加到交接文章列表中:
article_content=｛“标题”：响应(“文章”］(“标题”］，“身体”：响应(“文章”］(“身体”］，“id”：article_id}handoff_articles。附加（article_content）
该脚本还包括文章id，以便稍后将翻译上传到文章中。看到<一个href="//www.ying8.net/developer/documentation/help_center/help-center-api/using-the-help-center-api/using-the-help-center-api-to-manage-article-translations/#uploading-a-deliverable">上传可交付成果。
在循环的最后，handoff_articles变量包含要发送进行翻译的文章。该脚本将下载的文章保存到一个JSON文件中，您可以将该文件交给本地化供应商。
选项2 -下载文章编辑后开始时间
下载文章进行翻译的第二个选择是获取在特定开始时间之后编辑的所有文章。这与日期范围选项不同，因为您不指定结束时间。导出从开始时间到当前时间编辑过的所有文章。这种方法也被称为增加出口。
的增量导出版本<一个href="//www.ying8.net/developer/api-reference/help_center/help-center-api/articles/">文章列表端点查找在某个日期之后编辑的文章。端点看起来像这样:
https：//｛子域名}。亚博。com/api/v2/help_center/增量/文章？start_time=｛start_time}
在哪里{start_time}是一个<一个href="http://www.epochconverter.com/">时代的时间像1618348927。端点返回在开始时间之后发生元数据更改的任何项目。这包括对元数据的更改updated_at或edited_at。
使用端点以增量方式导出具有元数据更改的所有文章。对于每篇文章，比较edited_at时间与前一次导出的结束时间。如果文章是在结束时间之后编辑的，请将其添加到您的切换包中。
为确保在后续导出中不会跳过文章或再次获得相同的文章，请使用前一个导出的结束时间作为下一个导出的开始时间。例如，如果上次导出的结束时间是1617224682 (2021-03-31T21:04:42 UTC)的新纪元时间，则使用该时间作为下一次导出的开始时间。
例子
下面的Python脚本下载在上次导出结束时间为1618348927 (2021-04-13T21:22:07 UTC)之后编辑的文章。本例假设Zendesk帐户的子域名为“examp亚博le”(example.zendesk.com)。
进口json进口请求进口箭头handoff_articles=(］身份验证=（“your_email”，“your_password”）end_time=1618348927#2021-04-13T21：22：07UTCstart_time=end_time打印（f'-从{end_time}开始编辑文章'）edited_articles=(］url=f“https://example.亚博zendesk.com/api/v2/help_center/incremental/articles.json”而url：参数个数=｛“start_time”：start_time}响应=请求。得到（url，参数个数=参数个数，身份验证=身份验证）。json（）为文章在响应(“文章”］：如果箭头。得到（文章(“edited_at”］）。时间戳<end_time：继续edited_articles。附加（文章）如果响应(“next_page”］：start_time=响应(“end_time”］其他的：end_time=响应(“end_time”］url=没有一个打印（'-将内容打包并保存到handoff_articles.json'）为文章在edited_articles：article_content=｛“标题”：文章(“标题”］，“身体”：文章(“身体”］，“id”：文章(“id”］}handoff_articles。附加（article_content）与开放（“handoff_articles.json”，模式=' w '，编码=“utf - 8”）作为f：json。转储（handoff_articles，f，sort_keys=真正的，缩进=2）打印（f'-在下次导出时使用以下结束时间值:{end_time}）
它是如何工作的
脚本首先导入几个库。的<一个href="https://requests.readthedocs.io/en/latest/">请求类使API请求的处理更加简单<一个href="https://arrow.readthedocs.io/en/latest/">箭头库使使用日期更简单。的json库是一个原生Python库，但您需要安装请求和箭头库分开。看到的:
接下来，脚本声明一个变量来存储导出的文章。
handoff_articles=(］
下一行指定Zendesk凭据。亚博必须是代理或管理员才能使用增量项目导出端点。
身份验证=（“your_email”，“your_password”）
为了确保在连续的导出中不会跳过或导出两次项目，脚本使用前一次导出的结束时间设置导出的开始时间:
end_time=1618348927#2021-04-13T14：22：07（UTC-7）start_time=end_time
如果这是你的第一篇文章导出，选择一个日期和时间，把它插入<一个href="http://www.epochconverter.com/">历元时间转换器，并使用它作为end_time。
接下来，脚本将获得在前一次导出结束时间之后编辑的所有文章。
打印（f'-从{end_time}开始编辑文章'）edited_articles=(］url=f“https://support.亚博zendesk.com/api/v2/help_center/incremental/articles.json”而url：参数个数=｛“start_time”：start_time}响应=请求。得到（url，参数个数=参数个数，身份验证=身份验证）。json（）为文章在响应(“文章”］：如果箭头。得到（文章(“edited_at”］）。时间戳<end_time：继续edited_articles。附加（文章）
请注意:响应将只列出请求代理可以在帮助中心中查看的文章。
脚本检查和跳过(或仍在继续)到下一篇文章，如果一篇文章edited_at时间早于上一次导出的结束时间。的edited_at时间被转换为纪元时间，以便与箭头库的时间进行比较时间戳财产。如果文章通过测试，则意味着它在前一次导出之后进行了编辑，并且脚本将其附加到edited_articles列表。
您还可以通过指定未翻译的帮助中心部分并跳过这些部分中的文章来进一步定义导出的范围。例子:
为文章在响应(“文章”］：如果文章(“section_id”］在(3532453456，4345322342，5633456］：继续…
接下来，脚本对结果进行分页:
而url：…如果响应(“next_page”］：start_time=响应(“end_time”］其他的：end_time=响应(“end_time”］url=没有一个
增量式List Articles端点的分页方法与Help Center API的偏移式分页方法在两个重要方面有所不同。首先，端点每页最多返回1,000篇文章。第二,next_pageUrl没有指定下一页编号(页面= 2）.相反，它指定了一个新的开始时间，即当前页面上最后一项的最后一次更改的时间。响应还将此时间记录为end_time当前页面的。
例如，如果请求是初始的start_time是1617731790，响应可能包含以下内容next_page和end_time价值观:
“next_page”：“https://support.亚博zendesk.com/hc/api/v2/incremental/articles.json?start_time=1617733880”，“end_time”：1617733880，…
注意开始的时间next_page是否与初始开始时间不同，是否等于页面的开始时间end_time。
在到达最后一页的结果(当next_page是None)，脚本立即记录下一次导出使用的结束时间:
end_time=响应(“end_time”］
接下来，脚本将每篇文章的可翻译内容打包，并将该文章添加到交接文章列表中:
为文章在edited_articles：article_content=｛“标题”：文章(“标题”］，“身体”：文章(“身体”］，“id”：文章(“id”］}handoff_articles。附加（article_content）
在这一点上handoff_articles变量包含要发送进行翻译的所有文章。该脚本将文章保存到一个名为handoff_articles.json你可以把它交给本地化供应商。
脚本最后告诉用户为对象使用什么值end_time变量在下次导出:
打印（f'-在下次导出时使用以下结束时间值:{end_time}）
你也可以保存end_time值添加到文件中，并在脚本顶部添加一些代码，以便在后续导出中读取该文件。
选项3 -下载文章编辑之间的日期范围
下载文章的第三个选项是获取在指定日期范围内编辑过的所有文章。您可以使用<一个href="//www.ying8.net/developer/api-reference/help_center/help-center-api/search">搜索文章端点用于搜索这些文章。端点看起来像这样:
https：//｛子域名}。亚博。com/api/v2/help_center/文章/搜索。json？｛search_params}
例如，搜索在特定类别中更新过的文章2021-03-15和2021-03-31，你会提出以下API请求:
https：//例子。亚博。com/api/v2/help_center/文章/搜索。json？类别=21345&updated_after=2021-03-14&updated_before=2021-04-01
在本例中，updated_after日期实际上是3月15日开始日期的前一天updated_beforeDate是3/31结束日期后的一天。这捕获了在3月15日至3月31日(包括3月31日)的16天内更新的所有文章。
下一次切换时，请确保您不会错过文章或再次下载相同的文章，方法是使用上一个日期范围的结束日期作为updated_after下次下载的值。例如，要搜索在2021-04-01和2021-04-15之间更新的文章，可以使用上一个日期范围的3月31日结束日期作为updated_after下次下载日期:
https：//例子。亚博。com/api/v2/help_center/文章/搜索？类别=21345&updated_after=2021-03-31&updated_before=2021-04-16
例子
以下Python脚本下载在2021-03-15至2021-03-31期间编辑过的文章。本例假设Zendesk帐户的子域名为“examp亚博le”(example.zendesk.com)。
进口json进口请求进口箭头handoff_articles=(］category_id添加=(“36000171893”，“36000171913”，“36000175874”］updated_after=“2021-03-14”updated_before=“2021-04-01”打印（'-在日期范围内编辑文章'）edited_articles=(］url=“https://example.亚博zendesk.com/api/v2/help_center/articles/search.json”为category_id添加在category_id添加：打印（f-搜索{category_id}）参数个数=｛“类别”：category_id添加，“updated_after”：updated_after，“updated_before”：updated_before}而url：响应=请求。得到（url，参数个数=参数个数）。json（）为文章在响应(“结果”］：如果箭头。得到（文章(“edited_at”］）<箭头。得到（updated_after）。转变（天=1）：继续edited_articles。附加（文章）url=响应(“next_page”］打印（'-将内容打包并保存到handoff_articles.json'）为文章在edited_articles：article_content=｛“标题”：文章(“标题”］，“身体”：文章(“身体”］，“id”：文章(“id”］}handoff_articles。附加（article_content）与开放（“handoff_articles.json”，模式=' w '，编码=“utf - 8”）作为f：json。转储（handoff_articles，f，sort_keys=真正的，缩进=2）
它是如何工作的
与第二个选项一样，脚本从导入几个库开始。的<一个href="https://requests.readthedocs.io/en/latest/">请求类使API请求的处理更加简单<一个href="https://arrow.readthedocs.io/en/latest/">箭头库使使用日期更简单。的json库是一个原生Python库，但您需要安装请求和箭头库分开。看到的:
接下来，脚本声明一个变量来存储导出的文章，并声明另一个变量来指定包含要翻译的文章的类别。
handoff_articles=(］category_id添加=(“36000171893”，“36000171913”，“36000175874”］
您可以根据需要将搜索范围扩大或缩小。如果转换帮助中心中的所有内容，则可以使用List Categories端点来获得所有类别的id。如果只翻译几个节中的内容，则可以指定一个节id列表并只搜索这些节。
需要指定类别或部分。搜索文章端点要求您为每次搜索指定至少一个以下参数:
查询类别部分label_names
因为我们是按日期范围搜索，而不是按搜索词(查询)或根据标签，我们必须做出选择类别和部分。
接下来，脚本设置日期范围:
updated_after=“2021-03-14”updated_before=“2021-04-01”
接下来，脚本在每个类别中执行搜索。由于Search Articles端点不支持基于游标的分页，因此脚本使用偏移量分页。
edited_articles=(］url=“https://example.亚博zendesk.com/api/v2/help_center/articles/search.json”为category_id添加在category_id添加：打印（f-搜索{category_id}）参数个数=｛“类别”：category_id添加，“updated_after”：updated_after，“updated_before”：updated_before}而url：响应=请求。得到（url，参数个数=参数个数）。json（）为文章在响应(“结果”］：如果箭头。得到（文章(“edited_at”］）<箭头。得到（updated_after）。转变（天=1）：继续edited_articles。附加（文章）url=响应(“next_page”］
脚本检查和跳过(或仍在继续)到下一篇文章，如果一篇文章edited_at日期比搜索时间早updated_after日期——换句话说，如果文章最后一次编辑是在搜索日期范围之前的某个时间。
测试是必要的，因为一篇文章updated_at属性不仅记录文章最后一次编辑的时间，还记录其他文章更新，例如有人向文章添加了评论。因此，一篇文章可能不需要翻译。
一个完整的一天被添加到updated_after值(arrow.get (updated_after) .shift(天= 1))，因为arrow考虑的是…的准确时间updated_at一天的开始(2021-03-14T00:00:00+00:00)。如果没有添加的日期，脚本将返回当天编辑的所有文章，这超出了搜索日期范围。
接下来，脚本将每篇文章的可翻译内容打包，并将该文章添加到交接文章列表中:
为文章在edited_articles：article_content=｛“标题”：文章(“标题”］，“身体”：文章(“身体”］，“id”：文章(“id”］}handoff_articles。附加（article_content）
在这一点上handoff_articles变量包含要发送进行翻译的文章。该脚本将下载的文章保存到一个JSON文件中，您可以将该文件交给本地化供应商。
上传可交付成果
一段时间后，本地化供应商将把翻译结果发回给您。在开始之前，请与供应商坐下来讨论交付成果的格式和结构。例如，你可以同意供应商的意见，交付物应该是一个JSON文件，具有以下结构:
｛“fr”：(｛“身体”：“一，二，三”，“标题”：“索累”，“id”：21}，｛“身体”：“四，五，六”，“标题”：“半月形”，“id”：24}，｛“身体”：“Sept, huit, neuf”，“标题”：“魅幻之星”，“id”：39}］，“西文”：(｛“身体”：“Uno, dos, tres”，“标题”：“索尔”，“id”：21}，｛“身体”：Cuatro, cinco, seis，“标题”：“月神”，“id”：24}，｛“身体”：“Siete, ocho, nueve”，“标题”：“爱丝特雷娜”，“id”：39}］}
每个地区都列出了翻译成该语言的文章。有了这些信息，您可以编写一个脚本来阅读翻译，然后使用帮助中心API将它们上传到您的帮助中心。
下面的示例从一个JSON文件上传翻译，该JSON文件的结构与上面的类似。本例假设Zendesk帐户的子域名为“examp亚博le”(example.zendesk.com)。查看示例中的print语句和代码注释，了解它是如何工作的:
进口json进口请求身份验证=（“your_email”，“your_password”）打印（'-读取可交付文件'）与开放（2021 - 04 - 15 - _deliverable.json，模式=“r”，编码=“utf - 8”）作为f：可交付成果=json。负载（f）为语言环境在可交付成果：打印（f'\n-上传{地区}翻译'）为文章在可交付成果(语言环境］：article_id=文章(“id”］#得到需要确定的缺失翻译如果应该使用把或帖子请求url=f“https://example.亚博zendesk.com/api/v2/help_center/articles/ {article_id} /翻译/ missing.json”响应=请求。得到（url，身份验证=身份验证）。json（）missing_translations=响应(“场所”］如果语言环境在missing_translations：#新翻译->做一个帖子请求打印（f' -发布文章{article_id}的翻译'）post_url=f“https://example.亚博zendesk.com/api/v2/help_center/articles/ {article_id} / translations.json”数据=｛“翻译”：｛“场所”：语言环境，“标题”：文章(“标题”］，“身体”：文章(“身体”］}}响应=请求。帖子（post_url，json=数据，身份验证=身份验证）其他的：#现有翻译->做一个把请求打印（f' -为文章{article_id}添加翻译'）put_url=f“https://example.亚博zendesk.com/api/v2/help_center/articles/ {article_id} /翻译/{地区}. json的数据=｛“翻译”：｛“标题”：文章(“标题”］，“身体”：文章(“身体”］}}响应=请求。把（put_url，json=数据，身份验证=身份验证）
下一个步骤
本文仅用于教学目的。它的代码并不用于生产环境。但是，您可以复制代码并修改或扩展它以满足您的需求，同时还可以了解更多信息。例如，您可以将代码捆绑到一个函数中，以便在更大的应用程序中使用。例子:
defexport_edited_articles（last_exported，category_id添加）handoff_articles=(］start_time=last_exported…