Vision API 可偵測 Cloud Storage 中儲存的 PDF 和 TIFF 檔案,並將文字轉錄成文字。
您必須使用 files:asyncBatchAnnotate
函式,才能要求從 PDF 和 TIFF 偵測文件文字,這項函式會執行離線 (非同步) 要求,並使用 operations
資源提供狀態。
PDF/TIFF 要求的輸出內容會寫入在指定 Cloud Storage 值區中建立的 JSON 檔案。
限制
Vision API 可接受最多 2000 頁的 PDF/TIFF 檔案。較大的檔案會傳回錯誤。
驗證
files:asyncBatchAnnotate
要求不支援 API 金鑰。如要瞭解如何透過服務帳戶進行驗證,請參閱「使用服務帳戶」一文。
用於驗證的帳戶必須具備您為輸出內容指定的 Cloud Storage 值區存取權 (roles/editor
或 roles/storage.objectCreator
以上版本)。
您可以使用 API 金鑰查詢作業狀態,如需操作說明,請參閱「使用 API 金鑰」。
文件文字偵測要求
目前 PDF/TIFF 文件偵測功能僅適用於儲存在 Cloud Storage 值區中的檔案。回應 JSON 檔案也會儲存至 Cloud Storage 值區。

gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
,
來源:
美國人口普查局。
REST
使用任何要求資料之前,請先替換以下項目:
- CLOUD_STORAGE_BUCKET:儲存輸出檔案的 Cloud Storage 值區/目錄,以以下格式表示:
gs://bucket/directory/
- CLOUD_STORAGE_FILE_URI:Cloud Storage 值區中有效檔案 (PDF/TIFF) 的路徑。您至少必須具備檔案的讀取權限。示例:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- FEATURE_TYPE:有效的地圖項目類型。針對
files:asyncBatchAnnotate
要求,您可以使用下列地圖資料類型:DOCUMENT_TEXT_DETECTION
TEXT_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。提出要求的使用者或服務帳戶必須能寫入儲存桶。檔案名稱會是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/out_put_prefix
如要執行 TIFF 文字偵測,請使用
gcloud ml vision detect-text-tiff
指令,如以下範例所示:gcloud ml vision detect-text-tiff gs://my_bucket/input_file gs://my_bucket/out_put_prefix
其他語言
C#:請按照用戶端程式庫頁面上的 C# 設定說明操作,然後參閱 .NET 適用的 Vision 參考說明文件。
PHP:請按照用戶端程式庫頁面上的 PHP 設定操作說明操作,然後參閱 PHP 適用的 Vision 參考文件。
Ruby:請按照用戶端程式庫頁面上的 Ruby 設定說明操作,然後參閱 Ruby 適用的 Vision 參考文件。
多區域支援
您現在可以指定洲際資料儲存空間和 OCR 處理作業。目前支援下列地區:
us
:僅限美國eu
:歐盟
位置
Cloud Vision 可讓您控管專案資源的儲存和處理位置。具體來說,您可以設定 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 值區中有效圖片檔案的路徑。您至少必須具備檔案的讀取權限。示例:
gs://cloud-samples-data/vision/pdf_tiff/census2010.pdf
- CLOUD_STORAGE_BUCKET:儲存輸出檔案的 Cloud Storage 值區/目錄,以以下格式表示:
gs://bucket/directory/
- FEATURE_TYPE:有效的地圖項目類型。針對
files:asyncBatchAnnotate
要求,您可以使用下列地圖資料類型:DOCUMENT_TEXT_DETECTION
TEXT_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。提出要求的使用者或服務帳戶必須能寫入儲存桶。檔案名稱會是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 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
歡迎試用
如果您未曾使用過 Google Cloud,歡迎建立帳戶,親自體驗實際使用 Cloud Vision API 的成效。新客戶可以獲得價值 $300 美元的免費抵免額,可用於執行、測試及部署工作負載。
免費試用 Cloud Vision API