呼叫 Azure AI 視覺 3.2 GA 讀取 API
在本指南中，您將瞭解如何呼叫 v3.2 GA 讀取 API，以從影像擷取文字。 您將了解設定此 API 行為以符合您需求的不同方式。 本指南假設您建立視覺資源，並已取得金鑰與端點 URL。 如果您尚未這麼做，請遵循 快速入門 以開始使用。
OCR （閱讀） 版本
重要
選取最符合您需求的讀取版本。
| 輸入 | 範例 | 讀取版本 | 優點 |
|---|---|---|---|
| 影像：一般、野生影像 | 標籤、街道標誌和海報 | 適用於映像的 OCR （4.0 版） | 已針對具有效能增強的同步 API 進行一般非檔影像優化，可讓您更輕鬆地在用戶體驗案例中內嵌 OCR。 |
| 檔：數位和掃描，包括影像 | 書籍、文章和報表 | 文件智慧讀取模型 | 使用異步 API 針對大量文字掃描和數位文件進行優化，可協助大規模自動化智慧型手機文件處理。 |
關於 Azure AI 視覺 v3.2 GA 讀取
尋找最新的 Azure AI 視覺 v3.2 GA 讀取？ 所有未來的讀取 OCR 增強功能都屬於先前所列的兩項服務。 Azure AI 視覺 v3.2 沒有進一步的更新。 如需詳細資訊，請參閱呼叫 Azure AI 視覺 3.2 GA 讀取 API 和快速入門：Azure AI 視覺 v3.2 GA 讀取。
輸入需求
讀取呼叫會採用影像和文件作為其輸入。 他們具有下列需求：
- 支援的檔案格式：JPEG、PNG、BMP、PDF 和 TIFF
- 針對 PDF 和 TIFF 檔案，最多會處理 2000 頁（僅免費層的前兩頁）。
- 影像的檔案大小必須小於 500 MB（免費層為 4 MB），且大小至少為 50 x 50 像素，最多 10000 x 10000 像素。 PDF 檔案沒有大小限制。
- 針對 1024 x 768 影像的擷取文字高度下限為 12 像素。 這會對應到大約8個字型點文字，位於150 DPI。
注意
您不需要裁剪文字行的影像。 將整個影像傳送至讀取 API，其會辨識所有文字。
決定如何處理資料（選擇性）
指定 OCR 模型
根據預設，服務會使用最新的正式推出 （GA） 模型來擷取文字。 從 Read 3.2 開始， model-version 參數允許在指定 API 版本的 GA 和預覽模型之間進行選擇。 您指定的模型將用來擷取具有讀取作業的文字。
使用讀取作業時，請針對選擇性 model-version 參數使用下列值。
| 值 | 使用的模型 |
|---|---|
| 未提供 | 最新的 GA 模型 |
| latest | 最新的 GA 模型 |
| 2022-04-30 | 最新的 GA 模型。 164 種語言用於列印文字，9 種語言用於手寫文字，以及數個品質與效能增強功能 |
| 2022-01-30-preview | 預覽模型新增印度文、阿拉伯文和相關語言的列印文字支援。 針對手寫文字，新增對日文和韓文的支援。 |
| 2021-09-30-preview | 預覽模型新增對俄文和其他斯拉夫文語言的列印文字支援。 針對手寫文字，新增對簡體中文、法文、德文、義大利文、葡萄牙文和西班牙文的支援。 |
| 2021-04-12 | 2021 GA 模型 |
輸入語言
根據預設，服務會從影像或檔擷取所有文字，包括混合語言。 讀取 作業 具有語言的選擇性要求參數。 只有在您想要強制檔處理為該特定語言時，才提供語言代碼。 否則，服務可能會傳回不完整且不正確的文字。
自然閱讀順序輸出 （僅限拉丁語言）
根據預設，服務會以從左至右的順序輸出文字行。 選擇性地使用 readingOrder request 參數，使用 natural 更方便人類閱讀順序輸出，如下列範例所示。 這項功能僅支援拉丁語言。
選取用於擷取文字的頁面或頁面範圍
根據預設，服務會從檔中的所有頁面擷取文字。 或者，使用 pages request 參數來指定頁碼或頁面範圍，只擷取這些頁面的文字。 下列範例顯示具有 10 頁的檔，並針對這兩個案例擷取文字 - 所有頁面 （1-10） 和選取的頁面 （3-6）。
將數據提交至服務
您可以將本機映像或遠端映像提交至讀取 API。 針對本機，您會將二進位影像數據放在 HTTP 要求本文中。 針對遠端，您可以藉由格式化要求本文來指定影像的 URL，如下所示： {"url":"http://example.com/images/test.jpg"}。
讀取 API 的 讀取呼叫 會採用影像或 PDF 檔做為輸入，並以異步方式擷取文字。
https://{endpoint}/vision/v3.2/read/analyze[?language][&pages][&readingOrder]
呼叫會傳回名為的回應標頭欄位 Operation-Location。 值 Operation-Location 是 URL，其中包含下一個步驟中要使用的作業標識碼。
| 回應標頭 | 範例值 |
|---|---|
| Operation-Location | https://cognitiveservice/vision/v3.2/read/analyzeResults/49a36324-fc4b-4387-aa06-090cfbf0064f |
注意
Billing
Azure AI 視覺定價頁面包含讀取的定價層。 每個分析的影像或頁面都是一筆交易。 如果您使用包含 100 頁的 PDF 或 TIFF 檔呼叫作業，讀取作業會將其計算為 100 筆交易，而您將需支付 100 筆交易的費用。 如果您對作業進行 50 次呼叫，且每個呼叫都提交有 100 頁的檔，則您需支付 50 X 100 = 5000 筆交易的費用。
從服務取得結果
第二個步驟是呼叫 取得讀取結果 作業。 此作業接受讀取作業所建立之作業標識碼的輸入。
https://{endpoint}/vision/v3.2/read/analyzeResults/{operationId}
它會傳回 JSON 回應，其中包含 具有下列可能值的狀態 欄位。
| 值 | 意義 |
|---|---|
notStarted |
作業尚未啟動。 |
running |
正在處理作業。 |
failed |
作業失敗。 |
succeeded |
此作業已成功。 |
您會反覆呼叫此作業，直到傳回 成功 值為止。 使用 1 到 2 秒的間隔，以避免超過每秒的要求 （RPS） 速率。
注意
免費層會將要求速率限制為每分鐘 20 個呼叫。 付費層允許每秒 30 個要求 (RPS)，且可應要求增加。 請記下您的 Azure 資源識別碼和區域，並開啟 Azure 支援 票證，或連絡您的帳戶小組以要求每秒更高的要求率（RPS）。
當狀態欄位具有 succeeded 值時，JSON 回應會包含影像或檔中擷取的文字內容。 JSON 回應會維護可辨識字的原始行群組。 其中包含擷取的文字行及其周框方塊座標。 每個文字行都包含所有擷取的文字及其座標和信賴分數。
注意
提交至 Read 作業的數據會暫時加密並儲存在待用期間，然後刪除。 這可讓您的應用程式擷取擷取的文字作為服務回應的一部分。
範例 JSON 輸出
請參閱下列成功的 JSON 回應範例：
{
"status": "succeeded",
"createdDateTime": "2021-02-04T06:32:08.2752706+00:00",
"lastUpdatedDateTime": "2021-02-04T06:32:08.7706172+00:00",
"analyzeResult": {
"version": "3.2",
"readResults": [
{
"page": 1,
"angle": 2.1243,
"width": 502,
"height": 252,
"unit": "pixel",
"lines": [
{
"boundingBox": [
58,
42,
314,
59,
311,
123,
56,
121
],
"text": "Tabs vs",
"appearance": {
"style": {
"name": "handwriting",
"confidence": 0.96
}
},
"words": [
{
"boundingBox": [
68,
44,
225,
59,
224,
122,
66,
123
],
"text": "Tabs",
"confidence": 0.933
},
{
"boundingBox": [
241,
61,
314,
72,
314,
123,
239,
122
],
"text": "vs",
"confidence": 0.977
}
]
}
]
}
]
}
}
文字行的手寫分類（僅限拉丁語言）
回應包含分類每個文字行是否為手寫樣式，以及信賴分數。 這項功能僅支援拉丁語言。 下列範例顯示影像中文字的手寫分類。
