首页 文档智能 通用文档智能 API文档 API使用指南

API使用指南

本章节介绍文档智能解析的API使用前的准备工作，目前支持通用文档处理和文档格式转换相关的API。

建议您使用文档智能SDK来调用文档智能的OpenAPI。文档智能SDK已覆盖以下语言：

  • Java

  • Python3

  • Node.js

  • PHP

  • CSharp

  • Go

本文以Java语言为例介绍SDK的集成和API调用说明。其它语言的SDK请参见SDK概述。

准备Java SDK环境

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

然后在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>1.0.0</version>
    </dependency>
</dependencies>

获取AccessKey信息

创建AccessKey操作，请参见创建AccessKey。

说明

为避免主账号泄漏AccessKey带来的安全风险，建议您创建RAM用户，授予RAM用户文档智能相关的访问权限，再使用RAM用户的AccessKey调用SDK。详情请参见通过RAM用户控制文档智能使用权限。

如果担心RAM用户的AccessKey泄露，可以考虑通过创建RAM角色并使用STS临时授权的账号调用服务，详情请参见通过STS临时授权的账号调用服务。

调用异步任务提交类API

针对异步任务提交类API，大部分接口提供了本地文档上传和传入文档URL这两种调用方式。

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

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

异步任务提交类API列表，请参见API概览。

本地文档上传调用方式说明

您可以借助文档智能SDK实现本地文件上传调用方式，其中图片转Word、图片转Excel、图片转PDF接口不支持本地文件上传方式。

以下代码示例表示通过本地文件上传方式调用文档智能解析接口的异步任务提交类API，其他接口类似。

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 submit() throws Exception {
    Config config = new Config()
        // 前面准备好的您的AccessKey ID
        .setAccessKeyId(accessKeyId)
        // 前面准备好的您的AccessKey Secret
        .setAccessKeySecret(accessKeySecret);
    // 访问的域名，支持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);
}

返回结果如下所示，其中Id表示用于后续查询处理结果的流水号。

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

传入文档URL调用方式说明

您传入的文档URL必须为公网可访问下载的公网URL地址，无跨域限制，URL不带特殊转移字符。

以下代码示例表示通过文档URL方式调用文档智能解析接口的异步任务提交类API，其他接口类似。

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

public static void submit() throws Exception {
    Config config = new Config()
        // 前面准备好的您的AccessKey ID
        .setAccessKeyId(accessKeyId)
        // 前面准备好的您的AccessKey Secret
        .setAccessKeySecret(accessKeySecret);
    // 访问的域名，支持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);
}

返回结果如下所示，其中Id表示用于后续查询处理结果的流水号。

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

调用结果查询类API

针对结果查询类API，查询结果有处理中、处理成功、处理失败三种情况。

以下代码示例表示调用文档智能解析接口的结果查询类API，其他接口类似。

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

public static void submit() throws Exception {
    Config config = new Config()
        // 您的AccessKey ID
        .setAccessKeyId(accessKeyId)
        // 您的AccessKey Secret
        .setAccessKeySecret(accessKeySecret);
    // 访问的域名，支持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(response.getBody().getData());
}

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

处理中的返回结果如下所示，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-D0ECFE2D****",
  "Completed": true,
  "Data": [
    {
      "Type": "docx",
      "Size": 7940,
      "Url": "http://docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/convert/docmind-20220902-824b****/example.docx?Expires=1662190830&OSSAccessKeyId=XX&Signature=YY",
      "Md5": "36256a4c2db8e31e056aeeb8b871****"
    }
  ]
}

处理失败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"
}
阿里云首页 文档智能 相关技术圈