本文介绍如何使用阿里云PHP语言SDK开发包,调用文档智能解析的SubmitDocStructureJob接口(本地文件上传的异步提交服务接口)和GetDocStructureResult接口(解析结果查询服务接口),从文档中提取出层级结构、文本内容、KV字段、样式信息等。
查看OpenAPI文档
在调用OpenAPI前,建议您先阅读对应接口文档,了解、学习调用该接口所需要的参数及权限等。更多信息,请参见API概览。
准备工作
在使用PHP语言SDK方式调用文档智能解析的OpenAPI之前,请您完成如下准备工作。
环境准备
准备PHP SDK环境,安装SDK依赖包:
composer require alibabacloud/docmind-api-20220711 composer require alibabacloud/openapi-util composer require alibabacloud/tea --optimize-autoloader composer require alibabacloud/tea-rpc composer require alibabacloud/tea-fileform
一些用户可能由于网络问题无法安装,可以通过以下命令使用阿里云 Composer 全量镜像。
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
配置身份认证
创建RAM用户:您可以创建RAM用户并为其授权,实现不同RAM用户拥有不同资源访问权限的目的。当您的企业存在多用户协同访问资源的场景时,使用RAM可以按需为用户分配最小权限,避免多用户共享阿里云账号(主账号)密码或访问密钥,从而降低企业的安全风险。阿里云基于最佳实践,提供了常见场景的快速配置方式,且预置了对应RAM用户的权限策略,方便您快速创建RAM用户并授权。同时,您也可以根据自己的实际业务需求,采用手动配置的方式,手动创建RAM用户并授权。详细内容,请参见创建RAM用户并授权。
重要阿里云账号(主账号)默认拥有当前账号下所有云资源的Administrator权限,且无法修改。阿里云账号(主账号)的AccessKey泄露会威胁该账号下所有资源的安全。为保证账号安全,强烈建议您不要给阿里云账号(主账号)创建AccessKey,建议您创建专用于API访问的RAM用户并创建对应的AccessKey,完成最小化授权后,通过编程的方式访问阿里云资源。
不要将AccessKey ID和AccessKey Secret保存到工程代码里,避免AccessKey泄露。更多关于凭据的安全使用建议,请参见凭据的安全使用方案。
创建AccessKey。详细内容,请参见创建AccessKey。
添加阿里云SDK Credentials依赖。
composer require alibabacloud/credentials
配置身份认证:本文以配置文件的方式为例。详细内容,请参见管理访问凭据。
调用OpenAPI
调用接口提交文档处理任务
文档智能提供异步任务接口,PHP SDK仅支持传入文档URL的调用方式,不支持本地文档上传的调用方式。若您需要识别的文件为大文件,耗时较长,您可对config对象设置以下属性。
// 建立连接超时时间
$config->connectTimeout = 60000;
// 读取资源超时时间
$config->readTimeout = 60000;
传入文档URL提交任务
您传入的文档URL必须为公网可访问下载的公网URL地址,无跨域限制,URL不带特殊转义字符。以下代码示例表示通过文档URL方式调用异步任务提交类API。
use AlibabaCloud\SDK\Docmindapi\V20220711\Docmindapi;
use AlibabaCloud\SDK\Docmindapi\V20220711\Models\SubmitDocStructureJobRequest;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;
use AlibabaCloud\Tea\Exception\TeaUnableRetryError;
use AlibabaCloud\Credentials\Credential;
// 调用接口时,程序直接访问凭证,读取您的访问密钥(即AccessKey)并自动完成鉴权。
// 运行本示例前,请先完成步骤二:配置身份认证。
// 本示例使用默认配置文件方式,通过配置Credentials文件创建默认的访问凭证。
// 使用默认凭证初始化Credentials Client。
$bearerToken = new Credential();
$config = new Config();
// 访问的域名,支持IPv4和IPv6两种方式,IPv6请使用docmind-api-dualstack.cn-hangzhou.aliyuncs.com。
$config->endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
// 通过Credentials获取配置中的AccessKey ID。
$config->accessKeyId = $bearerToken->getCredential()->getAccessKeyId();
// 通过Credentials获取配置中的AccessKey Secret。
$config->accessKeySecret = $bearerToken->getCredential()->getAccessKeySecret();
$config->type = "access_key";
$config->regionId = "cn-hangzhou";
$client = new Docmindapi($config);
$request = new SubmitDocStructureJobRequest();
$runtime = new RuntimeOptions();
$runtime->maxIdleConns = 3;
$runtime->connectTimeout = 10000;
$runtime->readTimeout = 10000;
$request->fileName = "example.pdf";
$request->fileUrl = "https://example.com/example.pdf";
try {
$response = $client->submitDocStructureJob($request, $runtime);
var_dump($response->toMap());
} catch (TeaUnableRetryError $e) {
var_dump($e->getMessage());
var_dump($e->getErrorInfo());
var_dump($e->getLastException());
var_dump($e->getLastRequest());
}
返回结果如下所示:
{
"RequestId": "43A29C77-405E-4CC0-BC55-EE694AD0****",
"Data": {
"Id": "docmind-20220712-b15f****"
}
}
调用结果查询类API
以调用文档层级结构查询服务GetDocStructureResultRequest接口为例,查询结果有处理中、处理成功、处理失败三种情况。如下代码示例表示调用结果查询类API:
use AlibabaCloud\SDK\Docmindapi\V20220711\Docmindapi;
use AlibabaCloud\SDK\Docmindapi\V20220711\Models\GetDocStructureResultRequest;
use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\Tea\Exception\TeaUnableRetryError;
use AlibabaCloud\Credentials\Credential;
// 调用接口时,程序直接访问凭证,读取您的访问密钥(即AccessKey)并自动完成鉴权。
// 运行本示例前,请先完成步骤二:配置身份认证。
// 本示例使用默认配置文件方式,通过配置Credentials文件创建默认的访问凭证。
// 使用默认凭证初始化Credentials Client。
$bearerToken = new Credential();
$config = new Config();
// 访问的域名,支持IPv4和IPv6两种方式,IPv6请使用docmind-api-dualstack.cn-hangzhou.aliyuncs.com。
$config->endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
// 通过Credentials获取配置中的AccessKey ID。
$config->accessKeyId = $bearerToken->getCredential()->getAccessKeyId();
// 通过Credentials获取配置中的AccessKey Secret。
$config->accessKeySecret = $bearerToken->getCredential()->getAccessKeySecret();
$config->type = "access_key";
$config->regionId = "cn-hangzhou";
$client = new Docmindapi($config);
$request = new GetDocStructureResultRequest();
$request->id = "docmind-20220902-824b****";
$runtime = new RuntimeOptions();
$runtime->maxIdleConns = 3;
$runtime->connectTimeout = 10000;
$runtime->readTimeout = 10000;
try {
$response = $client->getDocStructureResult($request, $runtime);
var_dump($response->toMap());
} catch (TeaUnableRetryError $e) {
var_dump($e->getMessage());
var_dump($e->getErrorInfo());
var_dump($e->getLastException());
var_dump($e->getLastRequest());
}
返回结果
处理中的返回结果如下所示,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" }