PHP SDK User Guide
This topic describes how to use the Alibaba Cloud PHP software development kit (SDK) to call the `SubmitDocStructureJob` and `GetDocStructureResult` operations of Document Mind. The `SubmitDocStructureJob` operation is an asynchronous service for uploading local files. The `GetDocStructureResult` operation is a service for querying parsing results. You can use these operations to extract hierarchical structures, text content, key-value fields, and style information from documents.
View the OpenAPI documentation
Before you call an OpenAPI operation, read its API documentation to understand the required parameters and permissions. For more information, see API overview.
Preparations
Before you use the PHP SDK to call the OpenAPI operations of Document Mind, complete the following preparations.
Prepare the environment
Install the PHP SDK and its dependency packages:
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-fileformIf the installation fails because of network issues, run the following command to use the full Alibaba Cloud Composer mirror.
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
Configure identity authentication
Create a Resource Access Management (RAM) user. If multiple users in your organization need to access resources, use RAM to assign the least privilege required to each user. This practice avoids sharing your Alibaba Cloud account credentials and reduces security risks. Alibaba Cloud provides quick configurations based on best practices to help you create and authorize RAM users. You can also configure RAM users manually as needed. For more information, see Quick Start: Create and authorize a RAM user.
ImportantBy default, an Alibaba Cloud account has administrator permissions for all cloud resources under the account, and these permissions cannot be changed. A leaked AccessKey pair for an Alibaba Cloud account threatens all resources under that account. For security reasons, do not create an AccessKey pair for your Alibaba Cloud account. Instead, create a RAM user for API access. Create an AccessKey pair for the RAM user, grant the user the least privilege, and use the AccessKey pair to programmatically access Alibaba Cloud resources.
Do not hard-code your AccessKey ID and AccessKey secret into your project code to prevent leaks. For more information about how to use credentials securely, see Securely use credentials.
Create an AccessKey pair. For more information, see Create an AccessKey pair.
Add the Alibaba Cloud SDK Credentials dependency.
composer require alibabacloud/credentialsConfigure identity authentication. This topic uses a configuration file as an example. For more information, see Manage access credentials.
Call an OpenAPI operation
Call an operation to submit a document processing task
Document Mind provides asynchronous task operations. When you use the PHP SDK to call these operations, you can only pass a document URL. The SDK does not support uploading a local file. To process a large file that requires a long processing time, set the following properties for the `config` object.
// Connection timeout
$config->connectTimeout = 60000;
// Read timeout
$config->readTimeout = 60000;Submit a task by passing a document URL
The document URL must be a public URL that can be downloaded from the internet. The URL must not have cross-domain restrictions or contain special escape characters. The following sample code shows how to call an asynchronous task submission operation by passing a document URL.
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;
// When you call the operation, the program directly accesses the credential, reads your AccessKey pair, and automatically performs authentication.
// Before you run this example, complete Step 2: Configure identity authentication.
// This example uses the default configuration file to create the default access credential.
// Initialize the Credentials client with the default credential.
$bearerToken = new Credential();
$config = new Config();
// The endpoint. Both IPv4 and IPv6 are supported. For IPv6, use docmind-api-dualstack.cn-hangzhou.aliyuncs.com.
$config->endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
// Obtain the AccessKey ID from the configuration using Credentials.
$config->accessKeyId = $bearerToken->getCredential()->getAccessKeyId();
// Obtain the AccessKey secret from the configuration using Credentials.
$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());
}The following result is returned:
{
"RequestId": "43A29C77-405E-4CC0-BC55-EE694AD0****",
"Data": {
"Id": "docmind-20220712-b15f****"
}
}Call result query APIs
The `GetDocStructureResult` operation is used as an example. This operation queries the hierarchical structure of a document. The query result indicates whether the task is processing, successful, or has failed. The following sample code shows how to call a result query operation.
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;
// When you call the operation, the program directly accesses the credential, reads your AccessKey pair, and automatically performs authentication.
// Before you run this example, complete Step 2: Configure identity authentication.
// This example uses the default configuration file to create the default access credential.
// Initialize the Credentials client with the default credential.
$bearerToken = new Credential();
$config = new Config();
// The endpoint. Both IPv4 and IPv6 are supported. For IPv6, use docmind-api-dualstack.cn-hangzhou.aliyuncs.com.
$config->endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
// Obtain the AccessKey ID from the configuration using Credentials.
$config->accessKeyId = $bearerToken->getCredential()->getAccessKeyId();
// Obtain the AccessKey secret from the configuration using Credentials.
$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());
}Return values
The following result is returned if the task is still processing. The `Completed` field is `false`, which indicates that the task is not finished. You must continue polling until `Completed` is `true` or the maximum polling time is exceeded.
{ "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" }The following result is returned if the task is successful. The `Completed` field is `true`, which indicates that the task is finished. The `Status` field is `Success`, which indicates that the processing was successful. The detailed results are in the `Data` node.
{ "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": "SimHei", "color": "000000", "charScale": 0.95 }, { "styleId": 1, "underline": false, "deleteLine": false, "bold": false, "italic": false, "fontSize": 12, "fontName": "Microsoft YaHei", "color": "000000", "charScale": 1 } ], "layouts": [{ "text": "Test Title", "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": "This paragraph is for testing.", "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": "This paragraph", "pos": null, "styleId": 0 }, { "text": "is for testing.", "pos": null, "styleId": 1 } ] }], "logics": { "docTree": [{ "uniqueId": "xxxx9816e77caea338df554b80ab95c7", "level": 0, "link": { "children": [ ], "contains": [ ] }, "backlink": { "parent": [ "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 }] } } }The following result is returned if the task fails. The `Completed` field is `true`, which indicates that the task is finished. The `Status` field is `Fail`, which indicates that the processing failed. The response also includes an error `Code` and a detailed `Message`. For more information about error codes, see Error codes.
{ "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" }