Java SDK使用指南

本文介绍如何使用阿里云Java语言SDK开发包,调用文档智能解析的SubmitDocStructureJob接口(本地文件上传的异步提交服务接口)、SubmitDocStructureJob接口(URL上传的异步提交服务接口)和GetDocStructureResult接口(解析结果查询服务接口),从文档中提取出层级结构、文本内容、KV字段、样式信息等。

查看OpenAPI文档

在调用OpenAPI前,建议您先阅读对应接口文档,了解、学习调用该接口所需要的参数及权限等。更多信息,请参见API概览

准备工作

在使用Java语言SDK方式调用OpenAPI之前,请您完成如下准备工作。

准备Java SDK环境

  1. 在使用Java SDK前,您需要配置好Java SDK环境,Java版本要求Java 8及以上。

  2. 在Maven项目的pom.xml文件中,添加阿里云sdk核心库tea-openapi、文档智能sdk docmind_api20220711依赖,如下所示:

    <dependencies>
        <dependency>
            <groupId>com.aliyun</groupId>
            <artifactId>tea-openapi</artifactId>
            <version>0.2.5</version>
        </dependency>
        <dependency>
            <groupId>com.aliyun</groupId>
            <artifactId>docmind_api20220711</artifactId>
            <version>2.0.0</version>
        </dependency>
        <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>fastjson</artifactId>
                <version>1.2.68.noneautotype</version>
            </dependency>
    </dependencies> 

配置身份认证

  1. 创建AccessKey。详细内容,请参见创建AccessKey

  2. 创建RAM用户:您可以创建RAM用户并为其授权,实现不同RAM用户拥有不同资源访问权限的目的。当您的企业存在多用户协同访问资源的场景时,使用RAM可以按需为用户分配最小权限,避免多用户共享阿里云账号(主账号)密码或访问密钥,从而降低企业的安全风险。阿里云基于最佳实践,提供了常见场景的快速配置方式,且预置了对应RAM用户的权限策略,方便您快速创建RAM用户并授权。同时,您也可以根据自己的实际业务需求,采用手动配置的方式,手动创建RAM用户并授权。详细内容,请参见创建RAM用户并授权

    重要
    • 阿里云账号(主账号)默认拥有当前账号下所有云资源的Administrator权限,且无法修改。阿里云账号(主账号)的AccessKey泄露会威胁该账号下所有资源的安全。为保证账号安全,强烈建议您不要给阿里云账号(主账号)创建AccessKey,建议您创建专用于API访问的RAM用户并创建对应的AccessKey,完成最小化授权后,通过编程的方式访问阿里云资源。

    • 不要将AccessKey ID和AccessKey Secret保存到工程代码里,避免AccessKey泄露。更多关于凭据的安全使用建议,请参见凭据的安全使用方案

  3. 添加阿里云SDK Credentials依赖。具体代码如下:

    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>credentials-java</artifactId>
        <version>0.2.11</version>
    </dependency>
  4. 配置身份认证:本文以配置文件的方式为例。详细内容,请参见管理访问凭据

调用OpenAPI

文档智能解析接口为异步任务接口,需要先调用文档智能解析异步提交服务SubmitDocStructureJobAdvance或SubmitDocStructureJob接口进行异步任务提交,然后调用文档智能解析结果查询服务GetDocStructureResult接口进行结果轮询。

说明
  • 建议每10秒轮询一次,最多轮询120分钟,如果120分钟还未查询到处理完成结果,则视为处理超时。

  • 当异步任务处理提交后,用户可以在处理结束后的24小时之内查询处理结果,超过24小时后将无法查询到处理结果。

  • 图片转Word、图片转Excel、图片转PDF接口不支持文件上传方式。

调用接口提交文档处理任务

异步提交服务支持上传本地文件和url文件两种方式:

  • 上传本地文件的异步提交服务接口为:SubmitDocStructureJobAdvance接口。

  • 上传url文件的异步提交服务接口为:SubmitDocStructureJob接口。

若您需要识别的文件为大文件,耗时较长,可对config对象设置以下属性。

// 建立连接超时时间
config.connectTimeout = 60000;
// 读取资源超时时间
config.readTimeout = 60000;

使用本地文档提交异步任务

如下代码所示为调用SubmitDocStructureJobAdvance接口通过本地文件上传方式提交异步任务示例。

import com.aliyun.docmind_api20220711.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.docmind_api20220711.Client;
import com.aliyun.teautil.models.RuntimeOptions;
import java.io.File;
import java.io.FileInputStream;

public static void main(String[] args) throws Exception {
        submit();
    }
public static void submit() throws Exception {
    // 调用接口时,程序直接访问凭证,读取您的访问密钥(即AccessKey)并自动完成鉴权。
    // 运行本示例前,请先完成步骤二:配置身份认证。
    // 本示例使用默认配置文件方式,通过配置Credentials文件创建默认的访问凭证。
    // 使用默认凭证初始化Credentials Client。
    com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
    Config config = new Config()
        // 通过Credentials获取配置中的AccessKey ID。
        .setAccessKeyId(credentialClient.getAccessKeyId())
        // 通过Credentials获取配置中的AccessKey Secret。
        .setAccessKeySecret(credentialClient.getAccessKeySecret());
    // 访问的域名,支持IPv4和IPv6两种方式,IPv6请使用docmind-api-dualstack.cn-hangzhou.aliyuncs.com。
    config.endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
    Client client = new Client(config);
    // 创建RuntimeObject实例并设置运行参数。
    RuntimeOptions runtime = new RuntimeOptions();
    // 替换成具体异步任务提交类API接口的入参和方法,示例方法是文档智能解析。
    SubmitDocStructureJobAdvanceRequest advanceRequest = new SubmitDocStructureJobAdvanceRequest();
    File file = new File("D:\\example.pdf");
    advanceRequest.fileUrlObject = new FileInputStream(file);
    advanceRequest.fileName = "example.pdf";
    // 4 发起请求并处理应答或异常。
    SubmitDocStructureJobResponse response = client.submitDocStructureJobAdvance(advanceRequest, runtime);
    System.out.println(JSON.toJSON(response.getBody()));
}

返回结果

{
  "RequestId": "4FF7D611-782B-1557-AF71-6541E10A****",
  "Data": {
    "Id": "docmind-20220902-824b****"
  }
}

传入文档URL提交异步任务

您传入的文档URL必须为公网可访问下载的URL地址,无跨域限制,URL不带特殊转义字符。以下代码示例表示调用SubmitDocStructureJob接口通过传入文档URL方式调用异步任务提交类API。

import com.aliyun.docmind_api20220711.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.docmind_api20220711.Client;

public static void main(String[] args) throws Exception {
        submit();
    }
public static void submit() throws Exception {
    // 调用接口时,程序直接访问凭证,读取您的访问密钥(即AccessKey)并自动完成鉴权。
    // 运行本示例前,请先完成步骤二:配置身份认证。
    // 本示例使用默认配置文件方式,通过配置Credentials文件创建默认的访问凭证。
    // 使用默认凭证初始化Credentials Client。
    com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
    Config config = new Config()
        // 通过Credentials获取配置中的AccessKey ID。
        .setAccessKeyId(credentialClient.getAccessKeyId())
        // 通过Credentials获取配置中的AccessKey Secret。
        .setAccessKeySecret(credentialClient.getAccessKeySecret());
    // 访问的域名,支持IPv4和IPv6两种方式,IPv6请使用docmind-api-dualstack.cn-hangzhou.aliyuncs.com。
    config.endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
    Client client = new Client(config);
    // 替换成具体异步任务提交类API接口的入参和方法,示例方法是文档智能解析。
    SubmitDocStructureJobRequest request = new SubmitDocStructureJobRequest();
    request.fileName = "example.pdf";
    request.fileUrl = "https://example.com/example.pdf";
    SubmitDocStructureJobResponse response = client.submitDocStructureJob(request);
    System.out.println(JSON.toJSON(response.getBody()));
}

返回结果

{
  "RequestId": "4FF7D611-782B-1557-AF71-6541E10A****",
  "Data": {
    "Id": "docmind-20220902-824b****"
  }
}

调用结果查询类API

以调用文档层级结构查询服务GetDocStructureResultRequest接口为例,查询结果有处理中、处理成功、处理失败三种情况。如下代码示例表示调用结果查询类API:

import com.aliyun.docmind_api20220711.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.docmind_api20220711.Client;

public static void main(String[] args) throws Exception {
        submit();
    }
public static void submit() throws Exception {
    // 调用接口时,程序直接访问凭证,读取您的访问密钥(即AccessKey)并自动完成鉴权。
    // 运行本示例前,请先完成步骤二:配置身份认证。
    // 本示例使用默认配置文件方式,通过配置Credentials文件创建默认的访问凭证。
    // 使用默认凭证初始化Credentials Client。
    com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
    Config config = new Config()
        // 通过Credentials获取配置中的AccessKey ID。
        .setAccessKeyId(credentialClient.getAccessKeyId())
        // 通过Credentials获取配置中的AccessKey Secret。
        .setAccessKeySecret(credentialClient.getAccessKeySecret());
    // 访问的域名,支持IPv4和IPv6两种方式,IPv6请使用docmind-api-dualstack.cn-hangzhou.aliyuncs.com。
    config.endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
    Client client = new Client(config);
    GetDocStructureResultRequest resultRequest  = new GetDocStructureResultRequest();
    resultRequest.id = "docmind-20220902-824b****";
    // 替换成具体结果查询类API接口,示例方法是文档智能解析。
    GetDocStructureResultResponse response = client.getDocStructureResult(resultRequest);
   System.out.println(JSON.toJSON(response.getBody()));
}

返回结果

返回结果分为处理中、处理成功、处理失败三种情况。

  • 处理中的返回结果如下所示,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-D0ECFE2DFail",
      "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"
    }