网址转文档

概述

使用流程

异步方式：

1. 调用异步转换接口，提交网址和转换参数。
2. 接口立即返回token，表示任务已创建成功。
3. 后续通过以下任一方式获取结果： 调用查询结果接口轮询任务状态；或传入callbackurl，等待系统回调，详细见回调URL。

同步方式：

1. 调用同步转换接口，提交网址和转换参数。
2. 如果在限定时间内转换完成，则接口直接返回转换结果。
3. 如果在限定时间内未完成，则接口返回token和超时信息。
4. 返回token后，后续处理方式与异步方式相同：继续调用查询结果接口，或等待回调。
5. 同步调用详细见：同步调用

异同点：

• 相同点：两种方式的输入参数、转换能力、最终结果格式一致；当返回token后，后续都通过查询接口或回调URL获取最终结果。
• 不同点：异步方式会立即返回token；同步方式会优先等待转换完成，能在时限内完成时直接返回结果，超时后再退化为异步流程。

调用转换API需要签名，详细见文档附录：阿里签名。调用查询结果API无需签名。

网址转换

异步url：

https://url2doc.market.alicloudapi.com/v2/convert_async

同步url：

https://url2doc.market.alicloudapi.com/v2/convert_sync

HTTP方式： POST

Header中的Content-Type传入application/json

Body是JSON格式：

{"input": "https://www.example.com/article/123", "outputformat": "docx"}

必须签名才能调用成功，签名见阿里签名规则:

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

输出文件格式：

自定义参数：

顶层参数如下：

params中的参数如下，参数名必须使用下表中的JSON字段名。

网址网页相关参数：

通用输出参数：

输出PDF相关参数（outputformat为空或pdf时生效）：

输出文档相关参数（outputformat为docx、pptx、xlsx、txt、ofd时生效）：

输出图片相关参数（outputformat为jpg或png时生效）：

请求示例：

• 例1: 将网页URL转为Word

{"input": "https://www.example.com", "outputformat": "docx", "outfilename": "example"}

• 例2: 将网页URL转为PDF，并设置等待、压缩和文件名

{
  "input": "https://www.example.com/news/1001",
  "outputformat": "pdf",
  "outfilename": "news_1001",
  "params": {
    "urlwait": 3,
    "linearization": 1,
    "compress": 1,
    "watermark": "news"
  }
}

• 例3: 异步回调，并使用移动端页面转为Word

{
  "input": "https://www.example.com/post/abc",
  "outputformat": "docx",
  "outfilename": "post_abc",
  "params": {
    "ismobileurl": 1,
    "urlreadability": 1
  },
  "callbackurl": "https://api.example.com/url2doc/callback"
}

• 例4: 将网页URL转为PNG长图

{
  "input": "https://www.example.com/report",
  "outputformat": "png",
  "outfilename": "report",
  "params": {
    "imagesize": 1600
  }
}

返回数据结构【异步】：

result:

返回示例(成功状态)【异步】：

{
    "code":10000,
    "msg":"",
    "result":{"token":"YOUR_CREDENTIAL"}
}

返回示例(失败状态)【异步】：

{
    "code":40001,
    "msg":"ParmNotRight"
}

同步调用

同步调用的最大返回时间是60秒，如果60秒内转换结束则直接返回结果。否则会返回token，之后和异步方式一样可以调用查询结果接口查询该token的转换结果。所以同步调用如果页面内容复杂，无法保证在60秒内结束，则转为异步流程。

返回数据结构【同步】：

result:

返回示例(成功状态)【同步】：

{
	"code": 10000,
	"msg": "",
	"result": {
		"filesize": 17747,
		"fileurl": "https://file.duhuitech.com/o/xxx/xxx.docx",
		"status": "Done"
	},
	"token": "YOUR_CREDENTIAL"
}

{
	"code": 10000,
	"msg": "",
	"result": {
		"filesize": 17747,
		"fileurl": "https://file.duhuitech.com/o/xxx/xxx.png",
		"status": "Done"
	},
	"token": "YOUR_CREDENTIAL"
}

返回示例(超时状态)【同步】：

{
	"code": 40500,
	"msg": "Timeout, query token later",
	"token": "YOUR_CREDENTIAL"
}

查询结果

请求参数：

请求示例：

https://api.duhuitech.com/q?token=YOUR_TOKEN

无需签名，无调用次数限制

由于转换需要时间，页面越复杂，转换越久，故需要轮询查询接口来获得结果。查询频率可以是1s一次，也可以更长一些。 查询后先看status，如果是Done或Failed，则转换结束，停止轮询。如果是Doing或Pending，则继续轮询。

返回数据结构：

result:

返回示例(成功状态)：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"progress":0.02,
		"status":"Doing"
	}
}

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Done",
		"fileurl":"https://file.duhuitech.com/o/xxx/xxx.docx",
		"filesize":17747
	}
}

返回示例(失败状态)：

{
	"code":40000,
	"msg":"No such token"
}

备注：

• 系统会对单次任务时长、页面资源加载和目标URL可访问性做保护；页面过大、资源加载超时或目标URL不可访问时，任务可能失败或在同步调用中返回超时。
• 最大转换时长：1小时，超过时间未完成则自动失败。
• 转换完成后，下载链接有效时间：1小时。

上述最后2项有延长需求请联系客服：

---

回调URL：

用途： 客户可以自行部署服务器，系统转换结束后会调用客户提供的回调URL，直接发送转换结果，从而无需再轮询查询结果。

当设置了回调URL，转换结束后（无论成功失败），系统都会尝试调用该URL，具体如下：

以POST方式调用该URL，Header头中Content-Type: application/json

Body为JSON格式，内容和查询结果的结果相同，例如：

{
	"code":10000,
	"msg":"",
	"token":"YOUR_CREDENTIAL",
	"result":
	{
		"status":"Done",
		"fileurl":"https://file.duhuitech.com/o/xxx/xxx.docx",
		"filesize":17747
	}
}

服务端收到该POST后需在10秒内返回HTTP STATUS CODE 200，视为调用成功，否则系统认为回调失败，会再次尝试。规则如下：

系统共计最多会调用3次回调URL，如果第一次失败，则等待3秒后尝试第二次，如果第二次失败，则等待5秒后尝试第三次，如果第三次失败，则不再尝试。

回调URL超时时间10秒。

---

关于下载转换后的文件需支持302跳转

接口返回的下载地址（如 fileurl / fileurls）会经 HTTP 302 跳转到实际文件。浏览器会自动跟随。

以下方式默认会跟随跳转，一般无需额外配置：

wget、Python requests / urllib、Node.js axios / got / fetch、Java OkHttp / HttpURLConnection、Go net/http、C# HttpClient、PHP file_get_contents、Objective-C / Swift NSURLSession / URLSession（含 Alamofire）

少数默认不跟随，需手动打开：

• curl：加 -L，如 curl -L -o out.bin "下载地址"
• Java java.net.http.HttpClient：设置 .followRedirects(HttpClient.Redirect.NORMAL)
• PHP curl 扩展：设置 CURLOPT_FOLLOWLOCATION => true

若只拿到 302 响应、本地没有文件内容，多半是未跟随跳转，按上面说明打开对应选项即可。

---

阿里云独有部分：

当前接口场景为网页URL抓取，通常不涉及OSS内网地址。

---

错误码表：

返回的code如果是10000，代表成功，其余是失败

附录：阿里签名方式

参考链接：

https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/use-cases/call-apis

在调用API商品时，首先您需要了解采用哪种API认证方式，云市场API商品的认证方式主要有以下两种方式。两种方式可同时使用，您可以根据不同情况来选择。

• 简单身份认证（AppCode）

• 签名认证

简单身份认证（AppCode）

简单认证（AppCode）调用API，有两种方式，一种是将AppCode放在Header中进行调用，一种是将AppCode放在Query参数中进行调用。

方式一：将AppCode放在Header中

在请求Header中添加一个Authorization参数。

Authorization字段的值的格式为APPCODE ＋ 半角空格 ＋APPCODE值。格式如下：

Authorization:APPCODE AppCode值

示例：

Authorization:APPCODE YOUR_CREDENTIAL

方式二：将AppCode放在Query中

在请求Query中添加AppCode参数（同时支持appcode , appCode , APPCODE , APPCode四种写法）。

AppCode参数的值为AppCode的值。

示例：

http://www.aliyum.com?AppCode=YOUR_CREDENTIAL

参考链接：https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/user-guide/call-an-api-operation-by-using-an-appcode

签名认证

比较复杂，推荐用阿里自己的SDK来调用，参考链接：https://help.aliyun.com/zh/api-gateway/traditional-api-gateway/user-guide/use-digest-authentication-to-call-an-api