文档首页 > > API参考> API>

通用表格识别

通用表格识别

分享
更新时间:2021/03/17 GMT+08:00

功能介绍

识别表格图片中的文字内容,并将识别的结果以json格式返回给用户。返回结果将图片区域(words_region)划分为两类:纯文本区(text)和表格区(table),并返回表格结构(row, column)和文本信息。该接口的使用限制请参见约束与限制,详细使用指导请参见OCR服务使用简介章节。

图1 通用表格识别示例图

调试

您可以在API Explorer中调试该接口。

前提条件

在使用通用表格识别之前,需要您完成服务申请和认证鉴权,具体操作流程请参见申请服务认证鉴权章节。

URI

POST https://{endpoint}/v2/{project_id}/ocr/general-table

表1 路径参数

参数

是否必选

说明

endpoint

指定承载REST服务端点的服务器域名或IP,不同服务不同区域的endpoint不同,您可以从终端节点中获取。

例如,OCR服务在“华北-北京四”区域的“endpoint”“ocr.cn-north-4.myhuaweicloud.com”

project_id

项目ID,您可以从获取项目ID中获取。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头,从而通过身份认证,获得操作API的权限,响应消息头中X-Subject-Token的值即为Token。

Content-Type

String

发送的实体的MIME类型,参数值为“application/json”。

表3 请求Body参数

参数

是否必选

类型

说明

image

否,该参数与url二选一

String

图像数据,base64编码,要求base64编码后大小不超过10MB。图片最小边不小于15px,最长边不超过8192px,支持JPEG、JPG、PNG、BMP、TIFF格式。

url

否,该参数与image二选一

String

图片的url路径,目前支持:

  • 公网http/https url
  • OBS提供的url,使用OBS数据需要进行授权。包括对服务授权、临时授权、匿名公开授权,详情参见配置OBS访问权限
说明:
  • 接口响应时间依赖于图片的下载时间,如果图片下载时间过长,会返回接口调用失败。
  • 请保证被检测图片所在的存储服务稳定可靠,推荐使用OBS服务存储图片数据。

return_text_location

Boolean

返回文本块坐标及单元格坐标信息,可选值如下所示。

  • true:返回文本块和单元格坐标
  • false:不返回

如果未传入该参数时默认为false,即不返回。

return_confidence

Boolean

是否返回置信度的开关,可选值如下所示。

  • true:返回置信度
  • false:不返回置信度

如果未传入该参数,系统默认为“false”,即不返回置信度。

return_excel

Boolean

是否返回表格转换Microsoft Excel的base64编码字段。可选值包括:

  • true: 返回'excel'字段,表示xlsx格式的表格识别结果的base64编码
  • false: 不返回。默认为false

对返回的Excel编码,可用Python函数 base64.b64decode解码后保存为.xlsx文件。

响应参数

根据识别的结果,可能有不同的HTTP响应状态码(status code),状态码和响应参数说明如下。

状态码: 200

表4 响应Body参数

参数

参数类型

描述

result

GeneralTableResult object

调用成功时表示调用结果。

调用失败时无此字段。

表5 GeneralTableResult

参数

参数类型

描述

words_region_count

Integer

文字区域数目。

words_region_list

Array of WordsRegionList objects

文字区域识别结果列表,输出顺序从左到右,先上后下。

表6 WordsRegionList

参数

参数类型

描述

type

String

文字识别区域类型。

  • text:文本识别区域;
  • table:表格识别区域。

words_block_count

String

子区域识别文字块数目。

words_block_list

Array of GeneralTableWordsBlockList objects

子区域识别文字块列表,输出顺序从左到右,先上后下。

表7 GeneralTableWordsBlockList

参数

参数类型

描述

words

String

文字识别结果。当入参"return_text_location"为false时,每个单元格返回一个文本值,不同行文本由换行符 "\n" 拼接。

words_list

Array of Objects

单元格内文字段列表。输出顺序从左到右,从上到下。仅当入参"return_text_location"为true时存在。

rows

Array of integers

文字占用的行信息,编号从0开始,列表形式,数据类型为“Integer”。仅在表格区域内有效,即“type”字段为“table”时该字段有效。多个连续值表示参数值涉及多行(行列以表格内最小单元格来划分)。例如:rows:[0, 1, 2],表示这个参数值总共涉及三行。

columns

Array of integers

文字占用的列信息,编号从0开始,列表形式,数据类型为“Integer”。仅在表格区域内有效,即“type”字段为“table”时该字段有效。多个连续值表示参数值涉及多列(行列以表格内最小单元格来划分)。例如:cols: [0, 1, 2],表示这个参数值总共涉及三列。

location

Array of objects

文字块位置信息,列表形式,分别表示文字块4个顶点的x, y坐标;坐标原点为图片左上角,x轴沿水平方向,y轴沿竖直方向。

cell_location

Array of objects

单元格位置信息,列表形式,分别表示单元格4个顶点的x, y坐标;坐标原点为图片左上角,x轴沿水平方向,y轴沿竖直方向。

excel

String

表格图像转换为excel的base64编码,图像中的文字和表格按位置写入excel。对返回的excel编码可用base64.b64decode解码并保存为.xlsx文件。

confidence

Number

相关字段的置信度信息,取值范围0~1。

置信度越大,表示本次识别的对应字段的可靠性越高,在统计意义上,置信度越大,准确率越高。

置信度由算法给出,不直接等价于对应字段的准确率。

状态码: 400

表8 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码,具体请参见错误码

当出现错误码“ModelArts.4204”时,请参考为什么调用API时提示“ModelArts.4204”?章节。

调用成功时无此字段。

error_msg

String

调用失败时的错误信息。

调用成功时无此字段。

请求示例

  • “endpoint”即调用API的请求地址,不同服务不同区域的“endpoint”不同,具体请参见终端节点

    例如,通用表格识别服务部署在“华北-北京四”区域的“endpoint”“ocr.cn-north-4.myhuaweicloud.com”,请求URL为“https://ocr.cn-north-4.myhuaweicloud.com/v2/{project_id}/ocr/general-table”“project_id”为项目ID,获取方法请参见获取项目ID

  • 如何获取Token具体操作请参见构造请求
  • 请求示例(方式一:使用图片的base64编码)
    POST https://{endpoint}/v2/{project_id}/ocr/general-table
     Request Header:   
     Content-Type: application/json   
     X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...      
     Request Body:
     {   
        "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAg...",
        "return_text_location": true,
        "return_excel": true,
        "return_confidence":true
      }
  • 请求示例(方式二:使用图片URL)
    POST https://{endpoint}/v2/{project_id}/ocr/general-table
     Request Header:   
     Content-Type: application/json   
     X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...      
     Request Body:
     {
         "url":"https://BucketName.obs.xxxx.com/ObjectName",
         "return_confidence":false
      }
  • Python3语言请求代码示例(其他语言参照下列示例编写或使用OCR SDK)
    # encoding:utf-8
    
    import requests
    import base64
    
    url = "https://{endpoint}/v2/{project_id}/ocr/general-table"
    token = "用户获取得到的实际token值"
    headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}
    
    imagepath = r'./data/general-table-demo.png'
    with open(imagepath, "rb") as bin_data:
        image_data = bin_data.read()
    image_base64 = base64.b64encode(image_data).decode("utf-8")  # 使用图片的base64编码
    payload = {"image": image_base64}  # url与image参数二选一
    
    response = requests.post(url, headers=headers, json=payload)
    print(response.text)

响应示例

成功响应示例

当入参“return_text_location”“false”时,不返回坐标信息。
{
    "result": {
        "words_region_count": 2,
        "words_region_list": [
            {
               "type": "text",
               "words_block_count": 1,
               "words_block_list": [  
                    {
                       "words":"文字区域识别文字块1",
                       "confidence": 0.9991
                    }
               ]
            },
            {
               "type": "table",
               "words_block_count": 2,
               "words_block_list": [
                   {
                        "words":"表格区域识别文字块1",
                        "confidence": 0.9942,
                        "rows":[0],
                        "columns":[0]
                    },
                    {
                        "words":"表格区域识别文字块2",
                        "confidence": 0.9140,
                        "rows":[0],
                        "columns":[1,2]
                    }
                ]
            }
        ],
        "excel": "/1a/AEASABIAAD/4RFZRXhpZgAATU0AKgAAAAg..."
    }
}
当入参“return_text_location”“true”时,返回文本块坐标和单元格坐标,单元格内文本信息的返回为字典列表“words_list”
{
    "result": {
        "words_region_count": 2,
        "words_region_list": [
            {
               "type": "text",
               "words_block_count": 1,
               "words_block_list": [  
                    {
                       "words":"文字区域识别文字块1",
                       "location": [[13,476],
                                   [91, 476],
                                   [91, 560],
                                   [13, 560]],
                       "confidence": 0.9991
                    }
               ]
            },
            {
               "type": "table",
               "words_block_count": 1,
               "words_block_list": [
                   {
                       "rows": [0], 
                       "columns": [0], 
                       "cell_location": [[1042, 525],
                                        [1843, 525],
                                        [1843, 664],
                                        [1042, 664]],
 
                       "words_list": [{
                           "words":"单元格识别文字块1",
                           "confidence": 0.9942,
                           "location":  [[1053, 575],
                                        [1223, 575],
                                        [1223, 633],
                                        [1053, 633]]

                       },
                       {
                           "words":"单元格识别文字块2",
                           "confidence": 0.9140,
                           "location":  [[1678, 587],
                                        [1774, 587],
                                        [1774, 645],
                                        [1678, 645]]
                       }]
                    }
                ]
            }
        ]
        "excel": "/1a/AEASABIAAD/4RFZRXhpZgAATU0AKgAAAAg..."
    }
}

状态码:400

失败响应示例

{
    "error_code": "AIS.0103",
    "error_msg": "The image size does not meet the requirements."
}

状态码

状态码

描述

200

成功响应。

400

失败响应。

状态码请参见状态码

错误码

错误码请参见错误码

分享:

    相关文档

    相关产品

文档是否有解决您的问题?

提交成功!非常感谢您的反馈,我们会继续努力做到更好!
反馈提交失败,请稍后再试!

*必选

请至少选择或填写一项反馈信息

字符长度不能超过200

提交反馈 取消

如您有其它疑问,您也可以通过华为云社区论坛频道来与我们联系探讨

智能客服提问云社区提问