使用Tmxmall的文档解析API来进行多种类型文档的断句
背景
这个学期我在教学生怎么开发一个简易的CAT工具（往期成果参见：计算机辅助翻译工具开发竞赛作品展示：小译通），在开发过程中同学们遇到了一个文档解析的难题，即如何能把不同类型的文本都导入到CAT工具并自动完成分句。
这个功能非常不容易开发，但好在一者科技（Tmxmall）的张井、陈件已经把这个功能开发好，并做成API（应用程序接口）了，我们直接调用即可。
在这篇文章中我将简要介绍如何去调用他们的文档解析API。
正文
第一步：了解调用API的简单方法
Tmxmall的文档解析API地址是：
https://www.tmxmall.com/docs/openapi-fileparser/
在这个地址中可以看到这样的说明：
从中可知，文档解析API的作用是：“文档解析API提供了极其简单的编程接口，可以快速解析指定格式的文件，返回从文件中提取的文本和样式数据对象。”
我填写了上面的申请表，并很快拿到了所需的信息。
接下来就是去看他们提供的在线文档：
第一次看到这些信息的人会觉得不知所措，但实际上这部分写得非常简洁明了，我给大家解释一下：
知识点一：接口完整路径
其实这里的“接口完整路径”就是一个网址，但是这个网址你不能直接在浏览器访问，如果访问的话会出现下面的错误提示：
可见这不是一个我们常用的网址。
知识点二：请求方式：POST
我们在浏览器中直接输入这个网址并按回车键时，我们就是在“请求”（Request）这个网址。对于程序员来说，要通过写代码的方式来请求，而不是打开浏览器的方式，这时要用“POST”的方式来请求。
简单来说，“POST”就是“寄信”的意思，比如邮局叫“Post office”。
上一步的网址就是“收件人地址”，现在我们要给这个收件人写一封信，信封上除了要注明具体地址外，还要注明一些额外的信息，而信封里则要装入要发送的内容。
在我们现在的这个案例中，我们要发送的内容就是一个要去进行断句操作的文档（比如一个Word文档、一个PDF文档）。
在上面的截图中可知，Tmxmall的文档解析API支持的格式有：“pdf 、doc、ppt、xls、docx、pptx、xlsx、txt、xliff、sdlxlf、xlf、xml、csv、idml、html、htm、md、vsdx、mif、ods、yml、ots、odg、otp、odt、ott、srt、rtf、json、dita、ditamap。”
这个文件的大小限制是：“文件大小不超过100M，文件字符数不超过100000字,word文件或excel文件行数不能超过30000行。”
这个文件要以“multipart/form-data”方式提交。
知识点三：multipart/form-data
大家平时应该都填写过各种类型的表单吧，当你点击“提交”的那一刻，表单中的数据就会发送出去，而这些数据需要进行编码。一般来说，我们的表单会把数据以两种形式发送：
application/x-www-form-urlencoded
multipart/form-data
如果我们的表单中有要发送的文件，那么就需要使用multipart/form-data，否则就用application/x-www-form-urlencoded。
这也是为什么我们在学网页开发基础的时候，当学到上传文件时，会写这样的代码：
<html><body>
<form action="upload_file.php" method="post"enctype="multipart/form-data"><label for="file">Filename:</label><input type="file" name="file" id="file" /> <br /><input type="submit" name="submit" value="Submit" /></form>
</body></html>在上面的代码中就能看到enctype="multipart/form-data"。
知识点四：请求参数列表
现在你站在邮局里寄信，东西已经转到信封里了，收信人地址也有了，就差在信封上填写一些具体的信息了。这些信息就叫“请求参数”。
在Tmxmall的文档解析API中，我们需要提供以下参数：
file、user_name、client_id、from、to和de。
虽然在上面的截图中已经可以看到每个参数代表的意思，但我还是要再解释一下：
file：这个参数是用户上传的文件，但实际操作过程中并非直接把文件地址放到这个参数里，而是要把文件用multipart/form-data的形式编码后再放进去。
user_name：这个实际上就是你在Tmxmall上注册账号时的邮箱地址。
client_id：这个就是你成功申请到API后对方告诉你的一串密码，这个密码可以在登录账号后直接看到。
from：待解析文档的语言编码。
to：目标语言的语言编码。
在Tmxmall的文档中，简体中文的编码是：zh-CN，美式英文的编码是en-US，注意，不是zh_CN和en_US。
de：调用方，这个可以留空。
有了以上这些基础知识点，我们就可以开始写代码了。
第二步：开始使用PHP来调用API
根据我在本微信公众号中写得往期文章，我接下来依然会在XAMPP这个工具中来使用PHP作为主要编程语言。
我首先启动XAMPP，并在根目录中创建一个名为tmxmall的文件夹。
在该文件夹中，我创建一个名为index.php的文件，并在其中撰写以下代码：
<html><body>
<form action="upload.php" method="post"enctype="multipart/form-data"><label for="file">Filename:</label><input type="file" name="file" id="file" /> <br /><input type="submit" name="submit" value="Submit" /></form>
</body></html>在浏览器中运行这段代码的效果如下：
也就是说，我们可以直接在这里选择要上传的文件，并点击“Submit”，将这个文件发送到upload_file.php这个文件中。
接下来我们创建upload_file.php文件，并在其中撰写代码来显示上传文件的基本信息：
<?php
if ($_FILES["file"]["error"] > 0) { echo "Error: " . $_FILES["file"]["error"] . "<br />"; }else { echo "Upload: " . $_FILES["file"]["name"] . "<br />"; echo "Type: " . $_FILES["file"]["type"] . "<br />"; echo "Size: " . ($_FILES["file"]["size"] / 1024) . " Kb<br />"; echo "Stored in: " . $_FILES["file"]["tmp_name"]; } ?>代码来源：
https://www.w3school.com.cn/php/php_file_upload.asp
在上面这段代码中，$_Files["file"]就是我们上传的文件，
“$_FILES["file"]["error"]”用于显示文件上传的错误代码。
“$_FILES["file"]["name"] ”用于显示文件的名称。
“$_FILES["file"]["type"]”用于显示文件的类型。
“$_FILES["file"]["size"]”用于显示文件的大小。
“$_FILES["file"]["tmp_name"]”用于显示文件的临时存储地址。
有了这其中的一些信息我们就可以开始对文件进行编码了：
在PHP的新版本中有一个函数，名为curl_file_create，可以用于对文件编码，该函数需要三个参数：上传文件的路径、文件的类型和文件名。
对应上面的内容就是：
“$_FILES["file"]["size"]”、“$_FILES["file"]["type"]”和“$_FILES["file"]["name"] ”
所以，我们可以在文件上传后撰写一行代码来对文件进行编码：
<?php
if ($_FILES["file"]["error"] > 0) { echo "Error: " . $_FILES["file"]["error"] . "<br />"; }else { echo "Upload: " . $_FILES["file"]["name"] . "<br />"; echo "Type: " . $_FILES["file"]["type"] . "<br />"; echo "Size: " . ($_FILES["file"]["size"] / 1024) . " Kb<br />"; echo "Stored in: " . $_FILES["file"]["tmp_name"]; } $file = curl_file_create($_FILES["file"]["tmp_name"],$_FILES["file"]["type"],$_FILES["file"]["name"]); ?>信封里的东西包好了，下面就是填写信封上的内容：
$data = array( "file" => $file, "user_name" =>"pkucater@gmail.com", "client_id" =>"97003c01c9e39***********", "to" => "zh-CN", "from" => "en-US", "de" =>"");我们将所有的参数以数组（array）的形式来存储，并放入变量$data中。
最后一步就是启动调用API的流程，也就是开启“寄信”的操作。
在PHP中，主要是用cURL这个工具来完成的，代码如下：
$url = "http://api.tmxmall.com/v1/http/parseFile";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
$output = curl_exec($curl);
curl_close($curl);
echo $output;其中第一行代码是用于存储文档解析API的地址；
第三行代码用于启动curl工具；
第五行到第九行都是设置工具参数，分别是设置：
CURLOPT_URL：调用地址
CURLOPT_POST：当值为1时即为“POST”方法，并以“multipart/form-data”发送数据
CURLOPT_POSTFIELDS：其参数就是我们要发送的全部参数，即$data
CURLOPT_RETURNTRANSFER：其参数为1时，curl工具不会直接输出调用API的结果
curl_exec()：运行curl工具，开始调用API，并将返回的结果放到一个变量中
curl_close()：关闭curl工具
接下来我们选择一个简单的txt文件去做一下测试：
上传完成后，我们会看到以下结果：
这一大堆文字看起来很烦人，但是仔细一看会发现原文中的句子都被分割成一句一句的。
也就是说，我们成功调用了Tmxmall的文档解析API！
第三步：从API解析结果中抽取文本并以表格形式呈现
我们获取到的结果是JSON形式的，接下来我们可以将其转换为数组，并使用foreach语句来循环获取所有的结果，逐句显示出来。
代码如下：
$array = json_decode($output,true);
foreach($array["segments"] as $segment){ foreach($segment["srcSegmentAtoms"] as $Atom) { echo $Atom["data"]."<br>"; }}结果如下：
之所以我们的代码要这样写，实际上需要我们仔细去看Tmmall官方文档中诶出的返回结果的说明：
从上面这些说明可知，所有我们想获取的内容都在srcSegmentAtoms字段的data字段中。
这段代码不光适用于txt文件，如果我把同样的内容放到Word、PPT等文档中，效果是一样的，如下图：
上传一个Word文档：
上传一个PPT文档：
最后，我们再对结果进行一下格式化，将其显示在表格中：
代码：
$array = json_decode($output,true);
echo '<table border="1"> <tr> <th>原文</th> <th>百度翻译</th> <th>有道翻译</th> <th>谷歌翻译</th> </tr>';
foreach($array["segments"] as $segment){ foreach($segment["srcSegmentAtoms"] as $Atom) { echo '<tr><td>'.$Atom["data"].'<td>'; echo '<td></td>'; echo '<td></td></tr>'; }}
echo '</table>';结果：
大家知道接下来我准备做什么了吗？
有没有想过拿到一个待翻译的文本后，直接先看一下每句话对应的机器翻译的结果是怎样的？
有了这个API，以及之前我讲过的调用机器翻译API的方法（ParaTrans 2.0：百度、有道、搜狗、谷歌四款机器翻译服务大PK！）
我们的这种想法就可以实现了。我会在后面的文章中给大家介绍具体的实现方法。
总之，在今天的这篇文章中，我们给大家展示了如何调用Tmxmall的文档解析API，虽然文章写得长，但实际上只需要十几行代码。
最后，向Tmxmall表示感谢，你们真棒！