Vision API 可偵測並轉錄 Cloud Storage 中 PDF 和 TIFF 檔案的文字。
如要偵測 PDF 和 TIFF 檔案中的文件文字,必須使用 files:asyncBatchAnnotate 函式提出要求,該函式會執行離線 (非同步) 要求,並使用 operations 資源提供狀態。
PDF/TIFF 要求的輸出內容會寫入在指定 Cloud Storage bucket 中建立的 JSON 檔案。
限制
Vision API 接受最多 2,000 頁的 PDF 和 TIFF 檔案。如果檔案較大,系統會傳回錯誤。
驗證
files:asyncBatchAnnotate 要求不支援 API 金鑰。如要瞭解如何使用服務帳戶進行驗證,請參閱「使用服務帳戶」。
用於驗證的帳戶必須具備您為輸出指定的 Cloud Storage bucket 存取權 (roles/editor 或 roles/storage.objectCreator 以上)。
您可以使用 API 金鑰查詢作業狀態,操作說明請參閱「使用 API 金鑰」。
文件文字偵測要求
目前只有儲存在 Cloud Storage bucket 中的檔案,才能使用 PDF/TIFF 文件偵測功能。回應 JSON 檔案也會儲存至 Cloud Storage bucket。
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf,
資料來源:
美國人口普查局。
REST
使用任何要求資料之前,請先修改下列項目的值:
- CLOUD_STORAGE_BUCKET:用於儲存輸出檔案的 Cloud Storage bucket/目錄,格式如下:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI:Cloud Storage bucket 中有效檔案 (PDF/TIFF) 的路徑。您至少必須具備檔案的讀取權限。範例:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE:有效的特徵類型。如果是
files:asyncBatchAnnotate要求,您可以使用下列特徵類型:DOCUMENT_TEXT_DETECTIONTEXT_DETECTION
- PROJECT_ID: Google Cloud 專案 ID。
欄位專屬注意事項:
inputConfig:取代其他 Vision API 要求中使用的image欄位。其中包含兩個子欄位:gcsSource.uri:PDF 或 TIFF 檔案的 Google Cloud Storage URI (可供提出要求的使用者或服務帳戶存取)。mimeType:可接受的檔案類型之一:application/pdf或image/tiff。
outputConfig:指定輸出詳細資料。其中包含兩個子欄位:gcsDestination.uri:有效的 Google Cloud Storage URI。使用者或服務帳戶必須具備 bucket 的寫入權限,才能提出要求。檔案名稱會是output-x-to-y,其中x和y代表該輸出檔案中包含的 PDF/TIFF 頁碼。如果檔案存在,系統會覆寫其內容。batchSize:指定每個輸出 JSON 檔案應包含多少頁輸出內容。
HTTP 方法和網址:
POST https://vision.googleapis.com/v1/files:asyncBatchAnnotate
JSON 要求內文:
{
"requests":[
{
"inputConfig": {
"gcsSource": {
"uri": "CLOUD_STORAGE_FILE_URI"
},
"mimeType": "application/pdf"
},
"features": [
{
"type": "FEATURE_TYPE"
}
],
"outputConfig": {
"gcsDestination": {
"uri": "CLOUD_STORAGE_BUCKET"
},
"batchSize": 1
}
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/files:asyncBatchAnnotate"
PowerShell
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://vision.googleapis.com/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content
如果 asyncBatchAnnotate 要求成功,系統會傳回包含單一名稱欄位的回應:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
這個名稱代表長時間執行的作業,並具有相關聯的 ID (例如 1efec2285bd442df),可使用 v1.operations API 查詢。
如要擷取 Vision 註解回應,請將 GET 要求傳送至 v1.operations 端點,並在網址中傳遞作業 ID:
GET https://vision.googleapis.com/v1/operations/operation-id例如:
curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df
如果作業正在進行中:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "RUNNING", "createTime": "2019-05-15T21:10:08.401917049Z", "updateTime": "2019-05-15T21:10:33.700763554Z" } }
作業完成後,state 會顯示為 DONE,結果會寫入您指定的 Google Cloud Storage 檔案:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "DONE", "createTime": "2019-05-15T20:56:30.622473785Z", "updateTime": "2019-05-15T20:56:41.666379749Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse", "responses": [ { "outputConfig": { "gcsDestination": { "uri": "gs://your-bucket-name/folder/" }, "batchSize": 1 } } ] } }
輸出檔案中的 JSON 與圖片的 [文件文字偵測要求](/vision/docs/ocr)類似,但多了一個 context 欄位,顯示指定的 PDF 或 TIFF 位置,以及檔案中的頁數:
output-1-to-1.json
Go
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Vision Go API 參考文件。
如要向 Vision 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision API 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 Vision API Java 參考文件。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 Vision Node.js API 參考文件。
如要向 Vision 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Vision Python API 參考文件。
如要向 Vision 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
gcloud
您使用的 gcloud 指令取決於檔案類型。
如要執行 PDF 文字偵測,請使用
gcloud ml vision detect-text-pdf指令,如下列範例所示:gcloud ml vision detect-text-pdf gs://my_bucket/input_file gs://my_bucket/output_prefix
如要執行 TIFF 文字偵測,請使用
gcloud ml vision detect-text-tiff指令,如下列範例所示:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/output_prefix
其他語言
C#:請按照用戶端程式庫頁面上的 C# 設定操作說明完成相關步驟,然後參閱 .NET 適用的 Vision 參考文件。
PHP:請按照用戶端程式庫頁面上的 PHP 設定操作說明完成相關步驟,然後參閱 PHP 適用的 Vision 參考文件。
Ruby:請按照用戶端程式庫頁面上的 Ruby 設定操作說明完成相關步驟,然後參閱 Ruby 適用的 Vision 參考文件。
多區域支援
您現在可以指定洲際資料儲存空間和 OCR 處理作業。目前支援下列區域:
us:僅限美國eu:歐盟
位置
Cloud Vision 可讓您控管專案資源的儲存和處理位置。具體來說,您可以將 Cloud Vision 設為僅在歐盟境內儲存及處理資料。
根據預設,Cloud Vision 會在「全域」位置儲存及處理資源,因此無法保證資源會保留在特定位置或區域。如果選擇「歐盟」位置,Google 只會在歐盟境內儲存及處理您的資料。您和使用者可以從任何位置存取資料。
使用 API 設定位置
Vision API 支援全域 API 端點 (vision.googleapis.com) 和兩個區域端點:歐盟端點 (eu-vision.googleapis.com) 和美國端點 (us-vision.googleapis.com)。請使用這些端點進行區域專屬處理。舉例來說,如果只想在歐盟境內儲存及處理資料,請在 REST API 呼叫中使用 URI eu-vision.googleapis.com,而非 vision.googleapis.com:
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:annotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/images:asyncBatchAnnotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:annotate
- https://eu-vision.googleapis.com/v1/projects/PROJECT_ID/locations/eu/files:asyncBatchAnnotate
如要僅在美國境內儲存及處理資料,請搭配上述方法使用美國端點 (us-vision.googleapis.com)。
使用用戶端程式庫設定位置
Vision API 用戶端程式庫預設會存取全域 API 端點 (vision.googleapis.com)。如要僅在歐盟境內儲存及處理資料,您必須明確設定端點 (eu-vision.googleapis.com)。下列程式碼範例說明如何進行這項設定。
REST
使用任何要求資料之前,請先修改下列項目的值:
- REGION_ID:有效的區域位置 ID 之一:
us:僅限美國eu:歐盟
- CLOUD_STORAGE_IMAGE_URI:Cloud Storage bucket 中有效圖片檔的路徑。您至少必須具備檔案的讀取權限。
範例:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET:用於儲存輸出檔案的 Cloud Storage bucket/目錄,格式如下:
gs://bucket/directory/
- FEATURE_TYPE:有效的特徵類型。如果是
files:asyncBatchAnnotate要求,您可以使用下列特徵類型:DOCUMENT_TEXT_DETECTIONTEXT_DETECTION
- PROJECT_ID: Google Cloud 專案 ID。
欄位專屬注意事項:
inputConfig:取代其他 Vision API 要求中使用的image欄位。其中包含兩個子欄位:gcsSource.uri:PDF 或 TIFF 檔案的 Google Cloud Storage URI (可供提出要求的使用者或服務帳戶存取)。mimeType:可接受的檔案類型之一:application/pdf或image/tiff。
outputConfig:指定輸出詳細資料。其中包含兩個子欄位:gcsDestination.uri:有效的 Google Cloud Storage URI。使用者或服務帳戶必須具備 bucket 的寫入權限,才能提出要求。檔案名稱會是output-x-to-y,其中x和y代表該輸出檔案中包含的 PDF/TIFF 頁碼。如果檔案存在,系統會覆寫其內容。batchSize:指定每個輸出 JSON 檔案應包含多少頁輸出內容。
HTTP 方法和網址:
POST https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate
JSON 要求內文:
{
"requests":[
{
"inputConfig": {
"gcsSource": {
"uri": "CLOUD_STORAGE_IMAGE_URI"
},
"mimeType": "application/pdf"
},
"features": [
{
"type": "FEATURE_TYPE"
}
],
"outputConfig": {
"gcsDestination": {
"uri": "CLOUD_STORAGE_BUCKET"
},
"batchSize": 1
}
}
]
}
如要傳送要求,請選擇以下其中一個選項:
curl
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate"
PowerShell
將要求主體儲存在名為 request.json 的檔案中,然後執行下列指令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://REGION_ID-vision.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_ID/files:asyncBatchAnnotate" | Select-Object -Expand Content
如果 asyncBatchAnnotate 要求成功,系統會傳回包含單一名稱欄位的回應:
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
這個名稱代表長時間執行的作業,並具有相關聯的 ID (例如 1efec2285bd442df),可使用 v1.operations API 查詢。
如要擷取 Vision 註解回應,請將 GET 要求傳送至 v1.operations 端點,並在網址中傳遞作業 ID:
GET https://vision.googleapis.com/v1/operations/operation-id例如:
curl -X GET -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ https://vision.googleapis.com/v1/projects/project-id/locations/location-id/operations/1efec2285bd442df
如果作業正在進行中:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "RUNNING", "createTime": "2019-05-15T21:10:08.401917049Z", "updateTime": "2019-05-15T21:10:33.700763554Z" } }
作業完成後,state 會顯示為 DONE,結果會寫入您指定的 Google Cloud Storage 檔案:
{ "name": "operations/1efec2285bd442df", "metadata": { "@type": "type.googleapis.com/google.cloud.vision.v1.OperationMetadata", "state": "DONE", "createTime": "2019-05-15T20:56:30.622473785Z", "updateTime": "2019-05-15T20:56:41.666379749Z" }, "done": true, "response": { "@type": "type.googleapis.com/google.cloud.vision.v1.AsyncBatchAnnotateFilesResponse", "responses": [ { "outputConfig": { "gcsDestination": { "uri": "gs://your-bucket-name/folder/" }, "batchSize": 1 } } ] } }
如果您使用 DOCUMENT_TEXT_DETECTION 功能,輸出檔案中的 JSON 會類似於圖片的文件文字偵測回應;如果您使用 TEXT_DETECTION 功能,則會類似於文字偵測回應。輸出內容會多出 context 欄位,顯示指定的 PDF 或 TIFF 位置,以及檔案中的頁數:
output-1-to-1.json
Go
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Vision Go API 參考文件。
如要向 Vision 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision API 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 Vision API Java 參考文件。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 Vision Node.js API 參考文件。
如要向 Vision 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Vision Python API 參考文件。
如要向 Vision 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。