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

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

确定 API 路径

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

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

Service/Container

Batch Read File

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

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 视觉 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：文档的输入语言（来自可选的 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