文档

API详情

更新时间:

OpenSearch搜索开发工作台支持通过API的方式调用文档解析服务,您可以将服务集成到您的业务处理链路中,将非结构化数据解析为结构化数据并应用于业务。

服务名称

服务ID

服务描述

文档解析服务-001

ops-document-analyze-001

支持从非结构化文档中提取出标题、分段等逻辑层级结构,以及文本、表格、图片等信息,并以结构化的格式输出。

前提条件

  • 获取身份鉴权信息

    通过API调用OpenSearch搜索开发工作台服务时,需要对调用者身份进行鉴权,如何获取鉴权信息请参见获取API-KEY

  • 获取服务调用地址

    支持通过公网和VPC两种方式调用服务,详情请参见获取服务调用地址

公共说明

  • 请求body最大不能超过8MB。

创建异步提取任务

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/async

  • host:调用服务的地址,支持通过公网和VPC两种方式调用API服务,可参见获取服务调用地址Api—key两种方式.png

  • workspace_name:工作空间名称,例如default。

  • service_id: 系统内置服务id,例如ops-document-analyze-001。

请求参数

Header参数

  • API-KEY鉴权

参数

类型

必填

描述

示例值

Content-Type

String

请求类型:application/json

application/json

Authorization

String

API-Key

Bearer OS-d1**2a

Body参数

参数

类型

必填

描述

示例值

service_id

String

系统内置服务ID。

ops-document-analyze-001

document.url

String

文档URL地址,支持http、https协议(保证可以外网无状态下载)

与document.content二选一即可。

http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf

document.content

String

文档内容,用Base64Encode编码

与document.url二选一即可。

"aGVsbG8gd29ybGQ="

document.file_name

String

文件名,如果为空通过url推断,如果url也为空,则需要显式指定。

test.pdf

document.file_type

String

文件类型,如果为空从file_name的后缀推断,如果无法推断需要显式指定,如:pdf、doc、docx。

pdf

output.image_storage

String

图片存储方式

  • base64:默认方式

  • url:url有效期为3天

url

返回参数

参数

类型

描述

示例值

result.task_id

String

文档解析异步任务ID。

d5a4019e-853a-xxxx-b5b6-8053d9f5a9fc

请求示例

Mac系统下curl示例

curl -XPOST -H"Content-Type: application/json" \http: //****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-analyze/ops-document-analyze-001/async\
    -H "Authorization: Bearer 您的API-KEY" \
    -d '{
	"document": {
		"url": "http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/****/attention.pdf",
		"file_type": "pdf"
	},
	"output": {
		"image_storage": "base64"
	}
}'

windows系统下curl示例

curl -XPOST -H"Content-Type: application/json" "http://***-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-analyze/ops-document-analyze-001/async" -H "Authorization: Bearer 你的API-KEY"  -d "{	\"document\":{		\"url\":\"http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/attention.pdf\",		\"file_type\":\"pdf\"	},	\"output\":{		\"image_storage\":\"base64\"	}}"

响应示例

正常响应示例

{
    "request_id": "D5A4019E-853A-4E20-****-8053D9F5A9FC",
    "latency": 5.0,
    "http_code": 200,
    "result": {
        "task_id": "d5a4019e-853a-****-b5b6-8053d9f5a9fc"
    }
}

异常响应示例

在访问请求出错的情况下,输出的结果中会通过code和message指明出错原因。

{
    "request_id": "590A7EB8-AA84-****-AF31-8C35DC965972",
    "latency": 0.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "document.file_name required"
}

获取异步提取任务

请求方式

GET

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/async/task-status?task_id=${task_id}
  • host:调用服务的地址,支持通过公网和VPC两种方式调用API服务,可参见获取服务调用地址

  • workspace_name:工作空间名称,例如workspace01。

  • service_id: 系统内置服务id,例如ops-document-analyze-001。

  • task_id:创建文档解析响应中返回的异步任务 ID,例如d5a4019e-853a-xxxx-b5b6-8053d9f5a9fc。

请求参数

Header参数

  • API-KEY鉴权

参数

类型

必填

描述

示例值

Content-Type

String

请求类型:application/json

application/json

Authorization

String

API-Key

Bearer OS-d1**2a

返回参数

参数

类型

描述

示例值

result.task_id

String

文档解析异步任务ID。

"24c3ad59-XXXX-40cf-974b-b63d63e0****"

result.status

String

任务状态:

  • PENDING: 待处理

  • SUCCESS: 任务处理成功

  • FAIL: 任务失败终止

PENDING

result.error

String

status=FAIL时的错误信息内容,正常情况为空。

文档解密失败

result.data

Object

文档解析的结果。

markdown

result.data.content

String

文档解析结果-文档内容

  • pdf文档输出为markdown格式

  • 其他文档输出为html格式

"XXX"

result.data.content_type

String

文档解析结果-内容格式

  • markdown

  • html

markdown

result.data.page_num

Int

文档解析结果-文档页数。

15

request_id

String

系统对一次API调用赋予的唯一标识。

B4AB89C8-B135-xxxx-A6F8-2BAB801****

latency

Float/Int

请求耗时,单位ms。

10

usage

Object

本次调用产生的计量信息。

"usage": {

"token_count": 123,

"table_count": 5,

"image_count": 6

}

usage.token_count

Int

文档中字符个数。

1234

usage.table_count

Int

文档中表格个数。

5

usage.image_count

Int

文档中图片个数。

6

请求示例

Mac系统下curl示例

curl -XGET -H"Content-Type: application/json" \http: //****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-analyze/ops-document-analyze-001/async/task-status?task_id=110d6349-2e51-****-8bfb-25e5de434686\
    -H "Authorization: Bearer 您的API-KEY" \

Windows系统下curl示例

curl -XGET -H"Content-Type: application/json" "http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-analyze/ops-document-analyze-001/async/task-status?task_id=110d6349-2e51-****-8bfb-25e5de434686" -H "Authorization: Bearer 您的API-KEY"

响应示例

正常响应示例

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B680492",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is provided, Alibaba hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works....",
            "content_type": "markdown",
            "page_num": 15
        },
        "task_id": "24c3ad59-b196-****-974b-b63d63e05895"
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8
    }
}

异常响应示例

在访问请求出错的情况下,输出的结果中会通过code和message指明出错原因。

{
    "request_id": "0F94BD89-989C-****-963C-6E4F3FF99445",
    "latency": 3.0,
    "code": "BadRequest.TaskNotExist",
    "http_code": 404,
    "message": "task[2fda34f5-40b4-****-a9a2-3e2c1e807361] not exist"
}

创建同步提取任务

请求方式

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/document-analyze/{service_id}/sync

参数说明

  • host:调用服务的地址,支持通过公网和VPC两种方式调用API服务,可参见获取服务调用地址

  • workspace_name:工作空间名称,例如workspace01。

  • service_id: 系统内置服务id,例如ops-document-analyze-001。

请求参数

Header参数

  • API-KEY鉴权

参数

类型

必填

描述

示例值

Content-Type

String

请求类型:application/json

application/json

Authorization

String

API-Key

Bearer OS-d1**2a

Body参数

参数

类型

必填

描述

示例值

document.url

String

文档URL地址,支持http、https协议(保证可以外网无状态下载)

与document.content二选一即可。

http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/chatos/***/file-parser/samples/GB10767.pdf

document.content

String

文档内容,用Base64Encode编码

与document.url二选一即可。

"aGVsbG8gd29ybGQ="

document.file_name

String

文件名,如果为空从url推断,如果url为空需要显式指定。

test.pdf

document.file_type

String

文件类型,如果为空从file_name的后缀推断,如果无法推断需要显式指定,如:pdf、doc、docx。

pdf

output.image_storage

String

图片存储方式

  • base64,默认方式

  • url,有效期为3天

url

返回参数

参数

类型

描述

示例值

result.status

String

任务状态:

  • PENDING: 待处理

  • SUCCESS: 任务处理成功

  • FAIL: 任务失败终止

PENDING

result.error

String

status=FAIL时的错误信息内容,正常情况为空。

文档解密失败

result.data

Object

文档解析的结果。

markdown

result.data.content

String

文档解析结果-文档内容

  • pdf文档输出为markdown格式

  • 其他文档输出为html格式

"XXX"

result.data.content_type

String

文档解析结果-内容格式

  • markdown

  • html

markdown

result.data.page_num

Int

文档解析结果-文档页数。

15

request_id

String

系统对一次API调用赋予的唯一标识。

B4AB89C8-B135-xxxx-A6F8-2BAB801A2CE4

latency

Float/Int

请求耗时,单位ms。

10

usage

Object

本次调用产生的计量信息。

"usage": {

"token_count": 123,

"table_count": 5,

"image_count": 6

}

usage.token_count

Int

文档中字符个数。

1234

usage.table_count

Int

文档中表格个数。

5

usage.image_count

Int

文档中图片个数。

6

请求示例

Mac系统下curl示例

curl -XPOST -H"Content-Type: application/json" \http: //****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-analyze/ops-document-analyze-001/sync\
    -H "Authorization: Bearer 您的API-KEY" \
    -d '{
	"document": {
		"url": "http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/****/attention.pdf",
		"file_type": "pdf"
	},
	"output": {
		"image_storage": "base64"
	}
}'

Windows系统下curl示例

curl -XPOST -H"Content-Type: application/json" "http://****-hangzhou.opensearch.aliyuncs.com/v3/openapi/workspaces/workspace01/document-analyze/ops-document-analyze-001/sync" -H "Authorization: Bearer 您的API-KEY"  -d "{	\"document\":{		\"url\":\"http://opensearch-shanghai.oss-cn-shanghai.aliyuncs.com/****/attention.pdf\",		\"file_type\":\"pdf\"	},	\"output\":{		\"image_storage\":\"base64\"	}}"

响应示例

正常响应示例

{
    "request_id": "27F9CEC3-9052-****-83FF-E7957B689D04",
    "latency": 13.0,
    "http_code": 200,
    "result": {
        "status": "SUCCESS",
        "data": {
            "content": "Provided proper attribution is provided, Alibaba hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works....",
            "content_type": "markdown",
            "page_num": 15
        }
    },
    "usage": {
        "token_count": 31867,
        "table_count": 4,
        "image_count": 8
    }
}

异常响应示例

在访问请求出错的情况下,输出的结果中会通过code和message指明出错原因。

{
    "request_id": "6F33AFB6-A35C-****-AFD2-9EA16CCF4383",
    "latency": 2.0,
    "code": "InvalidParameter",
    "http_code": 400,
    "message": "JSON parse error: Cannot deserialize value of type `ImageStorage` from String \\"xxx\\"
}

状态码说明

HTTP 状态码

错误码

描述

200

-

请求成功,包括任务失败场景,实际任务状态需从result.status中判断

404

BadRequest.TaskNotExist

任务不存在

400

InvalidParameter

不合法请求

500

InternalServerError

内部错误

更多状态码说明,请参见状态码说明