从 Read v2.x 升级到 Read v3.x

本指南演示如何将现有容器或云 API 代码从 Read v2.x 升级到 Read v3.x。

确定 API 路径

使用下表根据要迁移到的 Read 3.x 版本确定 API 路径中的 版本字符串 。

接下来，使用以下部分来缩小作范围，并将 API 路径中的 版本字符串 替换为表中的值。 例如，对于 读取 v3.2 预览 版云和容器版本，请将 API 路径更新为 https://{endpoint}/vision/v3.2-preview.1/read/analyze[？language]。

服务/容器

Batch Read File

新的可选 语言 参数可用。 如果你不知道文档的语言，或者它可能是多语言的，请不要包含它。

Get Read Results

Get Read Operation Result 状态标志

调用 Get Read Operation Result 成功时，它会在 JSON 正文中返回状态字符串。

API 响应 （JSON）

请注意对 JSON 的以下更改：

• 在 v2.x 中， Get Read Operation Result 当状态为 Succeeded"时返回 OCR 识别 JSON。 在 v3.0 中，此字段为 succeeded.
• 若要获取页面数组的根目录，请将 JSON 层次结构从 recognitionResults 更改为 analyzeResult/readResults。 每页行和单词 JSON 层次结构保持不变，因此无需更改代码。
• 页面角度 clockwiseOrientation 已重命名为 angle，范围从 0 到 360 度更改为 -180 到 180 度。 根据代码，可能需要进行更改，因为大多数数学函数都可以处理任一范围。

v3.0 API 还引入了以下可选择性使用的改进：

• createdDateTime lastUpdatedDateTime因此，可以跟踪处理持续时间。
• version 告知用于生成结果的 API 版本。
• 每字 confidence。 此值经过校准，使值 0.95 表示识别正确的可能性为 95%。 使用置信度分数选择要发送到人工审阅的文本。

在版本 2.X 中，输出格式如下所示：

{
    {
    "status": "Succeeded",
    "recognitionResults": [
        {
        "page": 1,
        "language": "en",
        "clockwiseOrientation": 349.59,
        "width": 2661,
        "height": 1901,
        "unit": "pixel",
        "lines": [
            {
            "boundingBox": [
                67,
                646,
                2582,
                713,
                2580,
                876,
                67,
                821
            ],
            "text": "The quick brown fox jumps",
            "words": [
                {
                "boundingBox": [
                    143,
                    650,
                    435,
                    661,
                    436,
                    823,
                    144,
                    824
                ],
                "text": "The",
                },
        // The rest of result is omitted for brevity 
            
}

在 v3.0 中，它已进行调整：

{
    {
    "status": "succeeded",
    "createdDateTime": "2020-05-28T05:13:21Z",
    "lastUpdatedDateTime": "2020-05-28T05:13:22Z",
    "analyzeResult": {
    "version": "3.0.0",
    "readResults": [
        {
        "page": 1,
        "language": "en",
        "angle": 0.8551,
        "width": 2661,
        "height": 1901,
        "unit": "pixel",
        "lines": [
            {
            "boundingBox": [
                67,
                646,
                2582,
                713,
                2580,
                876,
                67,
                821
            ],
            "text": "The quick brown fox jumps",
            "words": [
                {
                "boundingBox": [
                    143,
                    650,
                    435,
                    661,
                    436,
                    823,
                    144,
                    824
                ],
                "text": "The",
                "confidence": 0.958
                },
// The rest of result is omitted for brevity 
    
}

仅限云服务

Recognize Text

Recognize Text 在 Azure AI 视觉 API 的所有版本中被弃用，是预览操作。 必须从 Recognize Text 迁移到 Read （v3.0）或 Batch Read File （v2.0，v2.1）。 版本 3.0 Read 包含较新的、更好的文本识别模型和其他功能，因此我们建议使用。 要从Recognize Text升级到Read：

Recognize Text 支持 模式 参数，但 Read 不支持它。 Read 自动支持手写文本和打印文本。

Read 在 v3.0 中引入了新的可选 语言 参数。 如果你不知道文档的语言，或者它可能是多语言的，请不要包含它。

Get Recognize Text Operation Result

Get Recognize Text Operation Result 状态标志

调用 Get Recognize Text Operation Result 成功时，它会在 JSON 正文中返回状态字符串字段。

API 响应 （JSON）

请注意对 JSON 的以下更改：

• 在版本 2.x 中， Get Read Operation Result 当状态为 Succeeded时返回 OCR 识别 JSON。 在版本 3.x 中，此字段为 succeeded.
• 若要获取页面数组的根目录，请将 JSON 层次结构从 recognitionResult 更改为 analyzeResult/readResults。 每页行和单词 JSON 层次结构保持不变，因此无需更改代码。

版本 3.0 API 还引入了以下可选择性使用的改进。 有关更多详细信息，请参阅 API 参考：

• createdDateTime lastUpdatedDateTime因此，可以跟踪处理持续时间。
• version 告知用于生成结果的 API 版本。
• 每字 confidence。 此值经过校准，使值 0.95 表示识别正确的可能性为 95%。 使用置信度分数选择要发送到人工审阅的文本。
• angle 文本的整体走向是以顺时针方向测量的，以度数测量，范围在 (-180, 180]。
• width 和 height 为您提供文档的尺寸，unit 则提供这些尺寸的单位（像素或英寸，具体取决于文档类型）。
• page 支持多页文档。
• language 文档的输入语言（来自可选 语言 参数）。

在版本 2.X 中，输出格式如下所示：

{
    {
    "status": "Succeeded",
    "recognitionResult": [
        {
        "lines": [
            {
            "boundingBox": [
                67,
                646,
                2582,
                713,
                2580,
                876,
                67,
                821
            ],
            "text": "The quick brown fox jumps",
            "words": [
                {
                "boundingBox": [
                    143,
                    650,
                    435,
                    661,
                    436,
                    823,
                    144,
                    824
                ],
                "text": "The",
                },
// The rest of result is omitted for brevity 
        
}

在版本 3.x 中，它进行了调整：

{
    {
    "status": "succeeded",
    "createdDateTime": "2020-05-28T05:13:21Z",
    "lastUpdatedDateTime": "2020-05-28T05:13:22Z",
    "analyzeResult": {
    "version": "3.0.0",
    "readResults": [
        {
        "page": 1,
        "angle": 0.8551,
        "width": 2661,
        "height": 1901,
        "unit": "pixel",
        "lines": [
            {
            "boundingBox": [
                67,
                646,
                2582,
                713,
                2580,
                876,
                67,
                821
            ],
            "text": "The quick brown fox jumps",
            "words": [
                {
                "boundingBox": [
                    143,
                    650,
                    435,
                    661,
                    436,
                    823,
                    144,
                    824
                ],
                "text": "The",
                "confidence": 0.958
                },
// The rest of result is omitted for brevity 
    
}

仅限容器

Synchronous Read