本文介绍如何使用阿里云Python语言SDK开发包，调用文档智能解析的SubmitDocStructureJob接口（本地文件上传的异步提交服务接口）、SubmitDocStructureJob接口（URL上传的异步提交服务接口）和GetDocStructureResult接口（解析结果查询服务接口），从文档中提取出层级结构、文本内容、KV字段、样式信息等。
查看OpenAPI文档
在调用OpenAPI前，建议您先阅读对应接口文档，了解、学习调用该接口所需要的参数及权限等。更多信息，请参见API概览。
准备工作
在使用Python语言SDK方式调用文档智能解析的OpenAPI之前，请您完成如下准备工作。
环境准备
下载并安装Python 3。如您已安装Python，请查看Python版本：
python --version。安装SDK核心库OpenAPI ，在终端设备中，逐条运行如下命令，安装环境依赖：
pip install alibabacloud_tea_openapi
pip install alibabacloud_docmind_api20220711==1.4.1配置身份认证
创建AccessKey。详细内容，请参见创建AccessKey。
创建RAM用户：您可以创建RAM用户并为其授权，实现不同RAM用户拥有不同资源访问权限的目的。当您的企业存在多用户协同访问资源的场景时，使用RAM可以按需为用户分配最小权限，避免多用户共享阿里云账号（主账号）密码或访问密钥，从而降低企业的安全风险。阿里云基于最佳实践，提供了常见场景的快速配置方式，且预置了对应RAM用户的权限策略，方便您快速创建RAM用户并授权。同时，您也可以根据自己的实际业务需求，采用手动配置的方式，手动创建RAM用户并授权。详细内容，请参见创建RAM用户并授权。
重要阿里云账号（主账号）默认拥有当前账号下所有云资源的Administrator权限，且无法修改。阿里云账号（主账号）的AccessKey泄露会威胁该账号下所有资源的安全。为保证账号安全，强烈建议您不要给阿里云账号（主账号）创建AccessKey，建议您创建专用于API访问的RAM用户并创建对应的AccessKey，完成最小化授权后，通过编程的方式访问阿里云资源。
不要将AccessKey ID和AccessKey Secret保存到工程代码里，避免AccessKey泄露。更多关于凭据的安全使用建议，请参见凭据的安全使用方案。
添加阿里云SDK Credentials依赖，具体代码如下：
pip install alibabacloud_credentials配置身份认证：本文以配置文件的方式为例。详细内容，请参见管理访问凭据。
调用OpenAPI
文档智能解析接口为异步任务接口，需要先调用文档智能解析异步提交服务SubmitDocStructureJobAdvance/SubmitDocStructureJob接口进行异步任务提交，然后调用文档智能解析结果查询服务GetDocStructureResult接口进行结果轮询。
建议每10秒轮询一次，最多轮询120分钟，如果120分钟还未查询到处理完成结果，则视为处理超时。
当异步任务处理提交后，用户可以在处理结束后的24小时之内查询处理结果，超过24小时后将无法查询到处理结果。
调用接口提交文档处理任务
异步提交服务支持本地文件和URL文件两种方式：
本地文件上传的异步提交服务接口为：SubmitDocStructureJobAdvance接口。
URL上传的异步提交服务接口为：SubmitDocStructureJob接口。
若您需要识别的文件为大文件，耗时较长，可对config对象设置以下属性。
# 建立连接超时时间
config.connect_timeout = 60000;
# 读取资源超时时间
config.read_timeout = 60000;使用本地文档提交异步任务
如下代码所示为调用SubmitDocStructureJobAdvance接口通过本地文件上传方式提交异步任务示例。
图片转Word、图片转Excel、图片转PDF接口不支持文件上传方式。
# -*- coding: utf-8 -*-
import sys
from typing import List
from alibabacloud_docmind_api20220711.client import Client as docmind_api20220711Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_docmind_api20220711 import models as docmind_api20220711_models
from alibabacloud_tea_util.client import Client as UtilClient
from alibabacloud_tea_util import models as util_models
from alibabacloud_credentials.client import Client as CredClient
def create_client() -> docmind_api20220711Client:
"""
@return: Client
@throws Exception
"""
# 调用接口时，程序直接访问凭证，读取您的访问密钥（即AccessKey）并自动完成鉴权。
# 运行本示例前，请先完成步骤二：配置身份认证。
# 本示例使用默认配置文件方式，通过配置Credentials文件创建默认的访问凭证。
# 使用默认凭证初始化Credentials Client。
cred=CredClient()
config = open_api_models.Config(
# 通过Credentials获取配置中的AccessKey ID
access_key_id=cred.get_credential().access_key_id,
# 通过Credentials获取配置中的AccessKey Secret
access_key_secret=cred.get_credential().access_key_secret
)
# 访问的域名
config.endpoint = f'docmind-api.cn-hangzhou.aliyuncs.com'
return docmind_api20220711Client(config)
if __name__ == '__main__':
client = create_client()
request = docmind_api20220711_models.SubmitDocStructureJobAdvanceRequest(
# file_url_object : 本地文件流
file_url_object=open("./example.pdf", "rb"),
# file_name ：文件名称。名称必须包含文件类型
file_name='123.pdf',
# file_name_extension : 文件后缀格式。与文件名二选一
file_name_extension='pdf'
)
runtime = util_models.RuntimeOptions()
try:
# 复制代码运行请自行打印 API 的返回值
response = client.submit_doc_structure_job_advance(request, runtime)
# API返回值格式层级为 body -> data -> 具体属性。可根据业务需要打印相应的结果。如下示例为打印返回的业务id格式
# 获取属性值均以小写开头，
print(response.body)
except Exception as error:
# 如有需要，请打印 error
UtilClient.assert_as_string(error.message)返回结果
{
"RequestId": "B2969F25-1A0B-5F08-9A16-EE694AD0****",
"Data": {
"Id": "docmind-20220922-b15f****"
}
}传入文档URL提交任务
您传入的文档URL必须为公网可访问下载的URL地址，无跨域限制，URL不带特殊转义字符。以下代码示例表示调用SubmitDocStructureJob接口通过传入文档URL方式调用异步任务提交类API。
# -*- coding: utf-8 -*-
import sys
from typing import List
from alibabacloud_docmind_api20220711.client import Client as docmind_api20220711Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_docmind_api20220711 import models as docmind_api20220711_models
from alibabacloud_tea_util.client import Client as UtilClient
from alibabacloud_credentials.client import Client as CredClient
def create_client() -> docmind_api20220711Client:
"""
@return: Client
@throws Exception
"""
# 调用接口时，程序直接访问凭证，读取您的访问密钥（即AccessKey）并自动完成鉴权。
# 运行本示例前，请先完成步骤二：配置身份认证。
# 本示例使用默认配置文件方式，通过配置Credentials文件创建默认的访问凭证。
# 使用默认凭证初始化Credentials Client。
cred=CredClient()
config = open_api_models.Config(
# 通过Credentials获取配置中的AccessKey ID
access_key_id=cred.get_credential().get_access_key_id(),
# 通过Credentials获取配置中的AccessKey Secret
access_key_secret=cred.get_credential().get_access_key_secret()
)
# 访问的域名
config.endpoint = f'docmind-api.cn-hangzhou.aliyuncs.com'
return docmind_api20220711Client(config)
if __name__ == '__main__':
client = create_client()
request = docmind_api20220711_models.SubmitDocStructureJobRequest(
# file_url : 文件url地址
file_url='https://example.com/example.pdf',
# file_name ：文件名称。名称必须包含文件类型
file_name='123.pdf',
# file_name_extension : 文件后缀格式。与文件名二选一
file_name_extension='pdf'
)
try:
# 复制代码运行请自行打印 API 的返回值
response = client.submit_doc_structure_job(request)
# API返回值格式层级为 body -> data -> 具体属性。可根据业务需要打印相应的结果。如下示例为打印返回的业务id格式
# 获取属性值均以小写开头，
print(response.body)
except Exception as error:
# 如有需要，请打印 error
UtilClient.assert_as_string(error.message)
返回结果
{
"RequestId": "43A29C77-405E-4CC0-BC55-EE694AD0****",
"Data": {
"Id": "docmind-20220712-b15f****"
}
}调用结果查询类API
针对结果查询类API，查询结果有处理中、处理成功、处理失败三种情况。以下代码示例表示调用结果查询类API。
# -*- coding: utf-8 -*-
import sys
from typing import List
from alibabacloud_docmind_api20220711.client import Client as docmind_api20220711Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_docmind_api20220711 import models as docmind_api20220711_models
from alibabacloud_tea_util.client import Client as UtilClient
from alibabacloud_credentials.client import Client as CredClient
def create_client() -> docmind_api20220711Client:
"""
@return: Client
@throws Exception
"""
# 调用接口时，程序直接访问凭证，读取您的访问密钥（即AccessKey）并自动完成鉴权。
# 运行本示例前，请先完成步骤二：配置身份认证。
# 本示例使用默认配置文件方式，通过配置Credentials文件创建默认的访问凭证。
# 使用默认凭证初始化Credentials Client。
cred=CredClient()
config = open_api_models.Config(
# 通过Credentials获取配置中的AccessKey ID
access_key_id=cred.get_credential().get_access_key_id(),
# 通过Credentials获取配置中的AccessKey Secret
access_key_secret=cred.get_credential().get_access_key_secret()
)
# 访问的域名
config.endpoint = f'docmind-api.cn-hangzhou.aliyuncs.com'
return docmind_api20220711Client(config)
if __name__ == '__main__':
client = create_client()
request = docmind_api20220711_models.GetDocStructureResultRequest(
# id : 任务提交接口返回的id
id='docmind-20220902-824b****'
)
try:
# 复制代码运行请自行打印 API 的返回值
response = client.get_doc_structure_result(request)
# API返回值格式层级为 body -> data -> 具体属性。可根据业务需要打印相应的结果。获取属性值均以小写开头
# 获取异步任务处理情况,可根据response.body.completed判断是否需要继续轮询结果
print(response.body.completed)
# 获取返回结果。建议先把response.body.data转成json，然后再从json里面取具体需要的值。
print(response.body)
except Exception as error:
# 如有需要，请打印 error
UtilClient.assert_as_string(error.message)
返回结果
分为处理中、处理成功、处理失败三种情况。
处理中的返回结果如下所示，Completed返回值为false，表示任务没有处理结束，仍在处理中。这种情况需要继续轮询，直到Completed返回值为true或者超过轮询最大时间。
{ "RequestId": "2AABD2C2-D24F-12F7-875D-683A27C3****", "Completed": false, "Code": "DocProcessing", "Message": "Document processing", "HostId": "ocr-api.cn-hangzhou.aliyuncs.com", "Recommend": "https://next.api.aliyun.com/troubleshoot?q=DocProcessing&product=docmind-api" }处理成功的返回结果如下所示，Completed返回值为true，表示任务处理结束，Status返回值为Success，表示处理成功。具体的处理结果在Data节点中。
{ "Status": "Success", "RequestId": "73134E1A-E281-1B2C-A105-D0EF****", "Completed": true, "Data": { "styles": [{ "styleId": 0, "underline": false, "deleteLine": false, "bold": true, "italic": false, "fontSize": 15, "fontName": "黑体", "color": "000000", "charScale": 0.95 }, { "styleId": 1, "underline": false, "deleteLine": false, "bold": false, "italic": false, "fontSize": 12, "fontName": "微软雅黑", "color": "000000", "charScale": 1 } ], "layouts": [{ "text": "测试标题", "index": 0, "uniqueId": "xxxx9816e77caea338df554b80ab95c7", "alignment": "center", "pageNum": [ 0 ], "pos": [{ "x": 405, "y": 192 }, { "x": 860, "y": 191 }, { "x": 860, "y": 236 }, { "x": 406, "y": 237 } ], "type": "title", "subType":"doc_title" }, { "text": "本段为测试内容", "index": 1, "uniqueId": "xxxx8606c213c01c12d70f98dcfb2525", "alignment": "left", "pageNum": [ 0 ], "pos": [{ "x": 187, "y": 311 }, { "x": 1075, "y": 311 }, { "x": 1076, "y": 373 }, { "x": 187, "y": 373 } ], "type": "text", "subType":"para", "lineHeight": 7, "firstLinesChars": 30, "blocks": [{ "text": "本段", "pos": null, "styleId": 0 }, { "text": "为测试内容", "pos": null, "styleId": 1 } ] }], "logics": { "docTree": [{ "uniqueId": "xxxx9816e77caea338df554b80ab95c7", "level": 0, "link": { "下级": [ ], "包含": [ ] }, "backlink": { "上级": [ "ROOT" ] } }], "paragraphKVs": null, "tableKVs": null }, "docInfo": { "docType": "pdf", "orignalDocName": "1.pdf", "pages": [{ "imageType": "JPEG", "imageUrl": "http://test.moshi.aliyuncs.com/docMind/image/xxxx3cccbfec45b48d3a8081c9c9659e/0", "angle": null, "imageWidth": 1273, "imageHeight": 1801, "pageIdCurDoc": 1, "pageIdAllDocs": 1 }] } } }处理失败的返回结果如下所示，处理失败Completed返回值为true，表示任务处理结束，Status返回值为Fail，表示处理失败，同时会返回失败Code和详细原因Message。访问错误码可以查看错误码详细介绍。
{ "RequestId": "A8EF3A36-1380-1116-A39E-B377BE27****", "Completed": true, "Status": "Fail" "Code": "UrlNotLegal", "Message": "Failed to process the document. The document url you provided is not legal.", "HostId": "docmind-api.cn-hangzhou.aliyuncs.com", "Recommend": "https://next.api.aliyun.com/troubleshoot?q=IDP.UrlNotLegal&product=docmind-api" }