Use self-managed OSS with docmind

Deploy and verify the solution

Create a RAM permission policy

1. Create a RAM role

• Log on to the RAM console. In the left-side navigation pane, choose Identity Management > Roles, and then click Create Role. For Select Role Type, choose Alibaba Cloud Account. This allows another Alibaba Cloud account to assume the role and access your resources.

• For Role Name, enter AliyunDocmindAccessingOssRole, and then click OK.

2. Create a custom permission policy

After creating the role, go to Permission Management > Policies and click Create Policy. Name the policy. This document uses the name testDocmindAccessOss. You can use the Visual Editor or the script editor. The following example uses the script editor to create a policy based on the principle of least privilege. For more details on OSS permissions, see Control access to OSS by using RAM policies.

Common examples of RAM policies

• This policy grants GetObject permission to read files from the your-bucket-directory/ path within the bucket named your-bucket-name. This allows docmind to access files only in this specified directory and prevents access to other paths.

• The docmind service writes the processing results to the [your-bucket-name]/[your-uid]/ path, where your-uid is the UID of your primary account. The policy grants GetObject and PutObject permissions for this path. The service requires the GetObject permission to return a URL when you query the results, and the PutObject permission is needed to write the analysis results to the path. This allows docmind to access only the [your-uid] folder and prevents access to other paths.

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "oss:GetObject"
            ],
            "Resource": "acs:oss:*:*:[your-bucket-name]/[your-bucket-directory]/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "oss:PutObject",
                "oss:GetObject"
            ],
            "Resource": "acs:oss:*:*:[your-bucket-name]/[your-uid]/*"
        }
    ],
    "Version": "1"
}

• Alternatively, you can use the Visual Editor to grant read, write, and access permissions for objects.

3. Attach the policy to the role

After creating the role, select it, go to Permission Management, and click Add Permissions. Select the custom policy you created (in this example, testDocmindAccessOss) and confirm the addition. For Resource Scope, select Account Level.

4. Edit the trust policy

The trust policy allows a trusted service principal (docmind-api.aliyuncs.com) to assume the role and acquire its permissions—the OSS permissions created in the previous steps.

{
  "Statement": [
    {
      "Action": "sts:AssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": [
          "docmind-api.aliyuncs.com"
        ]
      }
    }
  ],
  "Version": "1"
}

You have now successfully created a trust policy in your Alibaba Cloud account to authorize the docmind service to access the specified OSS directory.

Process OSS files with docmind

Before using the Java example, configure your Java SDK environment. Java 8 or later is required. Add the following dependencies to the pom.xml file of your Maven project:

<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.3</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>2.0.50</version>
    </dependency>
</dependencies> 

For example, when using the intelligent document analysis API, add the ossBucket and ossEndpoint parameters to your submission request.

import com.aliyun.docmind_api20220711.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.docmind_api20220711.Client;
import com.alibaba.fastjson.JSON;
public class Demo {
  public static void main(String[] args) throws Exception {
        submit();
    }
  public static void submit() throws Exception {
      // Initialize the credentials client by using the default provider chain.
      com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
      Config config = new Config()
          // Obtain the AccessKey ID from the credentials.
          .setAccessKeyId(credentialClient.getAccessKeyId())
          // Obtain the AccessKey Secret from the credentials.
          .setAccessKeySecret(credentialClient.getAccessKeySecret());
      // The endpoint of the service. Both IPv4 and IPv6 are supported. For IPv6, use docmind-api-dualstack.cn-hangzhou.aliyuncs.com.
      config.endpoint = "docmind-api.cn-hangzhou.aliyuncs.com";
      Client client = new Client(config);
      SubmitDocStructureJobRequest request = new SubmitDocStructureJobRequest();
      request.fileName = "example.pdf";
      // The fileUrl parameter can be one of the following:
      //   1. A publicly accessible URL, such as https://example.com/example.pdf.
      //   2. A file in an authorized object path, such as https://ossBucket.ossEndpoint/[your-bucket-directory]/filename.
      request.fileUrl = "https://example.com/example.pdf";
      // Specify your bucket name.
      request.ossBucket = "your-bucket-name";
      request.ossEndpoint = "oss-cn-hangzhou.aliyuncs.com";
      SubmitDocStructureJobResponse response = client.submitDocStructureJob(request);
      System.out.println(JSON.toJSON(response.getBody()));
   }
}

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
if __name__ == '__main__':
    # Initialize the credentials client by using the default provider chain.
    cred=CredClient()
    config = open_api_models.Config(
        # Obtain the AccessKey ID from the credentials.
        access_key_id=cred.get_credential().get_access_key_id(),
        # Obtain the AccessKey Secret from the credentials.
        access_key_secret=cred.get_credential().get_access_key_secret()
    )
    # The endpoint of the service.
    config.endpoint = f'docmind-api.cn-hangzhou.aliyuncs.com'
    client = docmind_api20220711Client(config)
    request = docmind_api20220711_models.SubmitDocStructureJobRequest(
        # file_url: The URL of the file.
        file_url='https://example.com/example.pdf',
        # file_name: The name of the file. The name must include the file extension.
        file_name='123.pdf',
        # file_name_extension: The file extension. You can specify either this parameter or file_name.
        file_name_extension='pdf',
        # oss_bucket: Your OSS bucket.
        oss_bucket='docmind-trust',
        # oss_endpoint: Your OSS endpoint.
        oss_endpoint='oss-cn-hangzhou.aliyuncs.com'
    )
    try:
        # When you run the code, print the API response as needed.
        response = client.submit_doc_structure_job(request)
        # The API response structure is body -> data -> specific attributes. You can print the results as needed. The following example shows how to print the returned `data` object.
        # Attribute names start with a lowercase letter.
        print(response.body.data)       
    except Exception as error:
        # Print the error message if an exception occurs.
        UtilClient.assert_as_string(error.message)

Example of a successful response:

{
  "RequestId": "43A29C77-405E-4CC0-BC55-EE694AD0****",
  "Data": {
    "Id": "docmind-20241209-b15f****"
  }  
}

Query results with the GetDocStructureResult API

Example

This Java SDK example shows how to query the results of an intelligent document analysis task. Pass the job ID returned by the submission request to the id parameter.

import com.aliyun.docmind_api20220711.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.docmind_api20220711.Client;
import com.alibaba.fastjson.JSON;
public class Demo {
  public static void main(String[] args) throws Exception {
          submit();
  }
  public static void submit() throws Exception {
      // Initialize the credentials client by using the default provider chain.
      com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
      Config config = new Config()
          // Obtain the AccessKey ID from the credentials.
          .setAccessKeyId(credentialClient.getAccessKeyId())
          // Obtain the AccessKey Secret from the credentials.
          .setAccessKeySecret(credentialClient.getAccessKeySecret());
      // The endpoint of the service. Both IPv4 and IPv6 are supported. For IPv6, use 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-20241209-824b****";
      GetDocStructureResultResponse response = client.getDocStructureResult(resultRequest);
      System.out.println(JSON.toJSON(response.getBody()));
  }
}

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
if __name__ == '__main__':
  	# Initialize the credentials client by using the default provider chain.
    cred=CredClient()
    config = open_api_models.Config(
        # Obtain the AccessKey ID from the credentials.
        access_key_id=cred.get_credential().get_access_key_id(),
        # Obtain the AccessKey Secret from the credentials.
        access_key_secret=cred.get_credential().get_access_key_secret()
    )
    # The endpoint of the service.
    config.endpoint = f'docmind-api.cn-hangzhou.aliyuncs.com'
    client = docmind_api20220711Client(config)
    request = docmind_api20220711_models.GetDocStructureResultRequest(
        # id: The ID returned by the job submission API.
        id='docmind-20241209-824b****'
    )
    try:
        # When you run the code, print the API response as needed.
        response = client.get_doc_structure_result(request)
        # The API response structure is body -> data -> specific attributes. You can print the results as needed. Attribute names start with a lowercase letter.
        # Check the status of the asynchronous task. You can use response.body.completed to determine whether to continue polling for the result.
        print(response.body.completed)
        # Get the result. We recommend that you first convert response.body.data to a JSON object and then extract the required values.
        print(response.body)
    except Exception as error:
        # Print the error message if an exception occurs.
        UtilClient.assert_as_string(error.message)

Example of a successful response:

{
    "Status": "Success",
    "RequestId": "73134E1A-E281-1B2C-A105-D0ECFE2DFail",
    "Completed": true,
    "Data": {
        "docInfo": {
            "docType": "pdf",
            "orignalDocName": "1.pdf",
            "pages": [
                {
                    "imageType": "JPEG",
                    "imageUrl": "http://docmind-trust.oss-cn-hangzhou.aliyuncs.com/19547627052365xx/publicDocStructure/docmind-20241209-f3007ea79d9a403a94c6ad624a4c852a/0.png?Expires=1733770459&OSSAccessKeyId=STS.XXX&Signature=VQkABf%2BCGEPpycMAFvMgMVV6W9U%3D&security-token=XXXXXXXXXX%2BgVWTjjTYBXMJC3fbNuDz2IHhMdHlvBuwXtv4%2BmW1T7v0Zlrh%2FTJRARErIWsxr9aNL9gCsZdI0ZWE4P%2BZW5qe%2BEE2%2FVjTZvqaLEcibIfrZfvCyESOm8gZ43br9cxi7QlWhKufnoJV7b9MRLGLaBHg8c7UwHAZ5r9IAPnb8LOukNgWQ4lDdF011oAFx%2BwgdgOadupTNt0aB0gelkrJP%2FNqsesKeApMybMslYbCcx%2Fdrc6fN6ilU5iVR%2Bb1%2B5K4%2Bom%2Bf7oHCXAUAu0%2FXbrePqoY0NnpwYqkrBqhIq%2FP5lPt0s%2BfYmp%2FsyhBCOvpOSSPbSZB2VE0RsRFbXDxQV8EYWxylurjnXvF%2BQxCnzp8uGin%2B2svzW55hiCFd2%2FzgUNuD0nrkDPnttVZ7%2Fl%2FYn9SLsRtGk7ToQ3rLd9GztUC8UsfzjZt2X3Z%2BGoABb2wsEAWkEeTkjHp5EdxaGWL0W0CQnmLOkWcRVb3H%2BRr7CVvzdTEPCJf7%2Bh8POBNbm8tciF0vcfLjGUs3%2FeiKBJtGaxK3SubvQJe99OiRFY0kcj%2Bjl5SQH%2B8Qy%2B5j5DzcqwhNdS1cMNbfIz9HbU5sU24CfYnwAELt9dtge7lMeccgAA%3D%3D",
                    "angle": null,
                    "imageWidth": 1273,
                    "imageHeight": 1801,
                    "pageIdCurDoc": 1,
                    "pageIdAllDocs": 1
                }
            ]
        },
        "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": {
                        "child": [],
                        "contains": []
                    },
                    "backlink": {
                        "parent": [
                            "ROOT"
                        ]
                    }
                }
            ],
            "paragraphKVs": null,
            "tableKVs": null
        }
    }
}