呼叫 Azure AI Vision v3.2 GA 讀取 API
本指南會說明如何呼叫 v3.2 GA 讀取 API 以從影像中擷取文字。 您將了解可設定此 API 行為的不同方式來符合您的需求。
下列步驟假設您已建立 電腦視覺 資源，並取得金鑰和端點 URL。 如果您尚未這麼做，請參閱快速入門以開始使用。
OCR (讀取) 版本
重要
選取最符合您需求的讀取版本。
| 輸入 | 範例 | 讀取版本 | 優點 |
|---|---|---|---|
| 影像：一般、野生影像 | 標籤、街道符號和海報 | 適用於影像的 OCR (4.0 版) | 已針對具有效能增強功能同步 API 的一般非文件影像進行最佳化，而效能增強功能同步 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 讀取。
決定如何處理資料 (選擇性)
指定 OCR 模型
根據預設，服務會使用最新的正式發行 (GA) 模型以擷取文字。 從讀取 v3.2 開始， model-version 參數允許在指定 API 版本的 GA 和預覽模型之間進行選擇。 您指定的模型是用來擷取具有讀取作業的文字。
使用讀取作業時，請使用下列值作為選擇性 model-version 參數。
| 值 | 已使用模型 |
|---|---|
| 未提供 | 最新 GA 模型 |
| 最新 | 最新 GA 模型 |
| 2022-04-30 | 最新 GA 模型。 164 種語言的列印文字和 9 種語言的手寫文字，以及數個品質與效能的增強功能 |
| 2022-01-30 | 新增印度文、阿拉伯文和相關語言的列印文字支援。 針對手寫文字，新增日文和韓文的支援。 |
| 2021-09-30 | 新增對俄文和其他斯拉夫文語言的列印文字支援。 針對手寫文字，新增簡體中文、法文、德文、義大利文、葡萄牙文和西班牙文的支援。 |
| 2021-04-12 | 2021 GA 模型 |
輸入語言
根據預設，服務會從您的影像或文件 (包含混合語言) 中擷取所有文字。 閱讀作業有為語言提供選擇性要求參數。 如果您希望強制讓文件按該特定語言處理，請只提供語言代碼。 否則，服務可能會傳回不完整且不正確的文字。
自然讀取順序 (僅適用於拉丁語言)
根據預設，服務會以從左至右的順序輸出文字行。 (選擇性) 使用 readingOrder 要求參數，以 natural 取得更容易閱讀的讀取順序輸出，如下列範例所示。 這項功能僅支援拉丁語言。
選取文字擷取的頁面或頁面範圍
根據預設，服務會從文件中的所有頁面擷取文字。 (選擇性) 使用 pages 要求參數來指定頁碼或頁面範圍，以便只從這些頁面擷取文字。 下列範例顯示具有 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/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4 |
注意
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 |
作業成功。 |
您將反覆呼叫此作業，直到其與 succeeded 值一併傳回為止。 使用 1 到 2 秒的間隔，以避免超過每秒的要求 （RPS） 速率。
注意
免費層會限制要求速率為每分鐘 20 次呼叫。 付費層允許 30 個可依要求增加的 RPS。 請記下您的 Azure 資源識別碼和區域，並開啟 Azure 支援 票證，或連絡您的帳戶小組以要求較高的 RPS 費率。
當 [狀態] 欄位有 succeeded 值時，JSON 回應會包含從您影像或文件擷取的文字內容。 JSON 回應會維持已辨識文字的原始行群組。 其包含擷取的文字行和它們的週框方塊座標。 每一個文字行都包含所有擷取的文字，以及它們的座標與信賴度分數。
注意
提交給讀取作業的資料會暫時加密並經過短暫待用儲存，然後再刪除。 這能讓您的應用程式收到服務回應中的已擷取文字。
範例 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
}
]
}
]
}
]
}
}
文字行的手寫分類 (僅適用於拉丁語言)
回應會包含每行文字是否為手寫樣式的分類，以及信賴度分數。 此功能僅適用於拉丁語言。 下列範例顯示影像中文字的手寫分類。
