共用方式為

從 Read v2.x 升級至 Read v3.x

本指南說明如何將您現有的容器或雲端 API 程式碼從 Read v2.x 升級至 Read v3.x。

確認您的 API 路徑

使用下表來根據您要移轉至的 Read 3.x 版本以判斷 API 路徑中的版本字串。

產品類型 Version 3.x API 路徑中的版本字串
Service Read 3.0、3.1 或 3.2 分別是 v3.0、v3.1 或 v3.2
Service Read 3.2 預覽 v3.2-preview.1
Container Read 3.0 預覽或 Read 3.1 預覽 分別是 v3.0 或 v3.1-preview.2

接著，使用以下各節縮小作業範圍，並將 API 路徑中的版本字串取代為表格中的值。 例如，對於 Read v3.2 預覽的雲端和容器版本，請將 API 路徑更新為 https://{endpoint}/vision/v3.2-preview.1/read/analyze[?language]。

Service/Container

Batch Read File

閱讀 2.x 閱讀3.x
https://{endpoint}/vision/v2.0/read/core/asyncBatchAnalyze https://{endpoint}/vision/<版本字串>/read/analyze[?language]

有新的選擇性 language 參數可供使用。 如果您不知道文件的語言，或可能是多語系，請勿包含它。

Get Read Results

閱讀 2.x 閱讀3.x
https://{endpoint}/vision/v2.0/read/operations/{operationId} https://{endpoint}/vision/<版本字串>/read/analyzeResults/{operationId}

Get Read Operation Result 狀態旗標

Get Read Operation Result呼叫成功時，它會在 JSON 主體中傳回狀態字串。

閱讀 2.x Read 3.x
"NotStarted" "notStarted"
"Running" "running"
"Failed" "failed"
"Succeeded" "succeeded"

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 Vision API 中都已棄用。 您必須從 Recognize Text 遷移至 Read (v3.0) 或 Batch Read File (v2.0、2.1)。 3.0 Read 版包含較新的、更好的文字辨識模型和其他功能，因此我們建議使用。 從 Recognize Text 升級至 Read：

辨識文字 2.x 閱讀3.x
https://{endpoint}/vision/v2.0/recognizeText[?mode] https://{endpoint}/vision/<版本字串>/read/analyze[?language]

Recognize Text 支援 mode 參數，但 Read 不支援它。 Read 會自動支援手寫和列印文字。

Read 在 v3.0 中引進新的選擇性 語言 參數。 如果您不知道文件的語言，或可能是多語系，請勿包含它。

Get Recognize Text Operation Result

辨識文字 2.x 閱讀3.x
https://{endpoint}/vision/v2.0/textOperations/{operationId} https://{endpoint}/vision/<版本字串>/read/analyzeResults/{operationId}

Get Recognize Text Operation Result 狀態旗標

呼叫 Get Recognize Text Operation Result 成功時，它會傳回 JSON 主體中的狀態字串字段。

辨識文字 2.x 閱讀 3.x
"NotStarted" "notStarted"
"Running" "running"
"Failed" "failed"
"Succeeded" "succeeded"

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

閱讀2.0 閱讀3.x
https://{endpoint}/vision/v2.0/read/core/Analyze https://{endpoint}/vision/<版本字串>/read/syncAnalyze[?language]
  • Last updated on