Vision API では、Cloud Storage に保存されている PDF ファイルと TIFF ファイルのテキストを検出して転写できます。
PDF と TIFF からのドキュメント テキスト検出は、files:asyncBatchAnnotate
関数を使用してリクエストする必要があります。これにより、オフライン(非同期)リクエストが行われ、operations
リソースでそのステータスを確認できるようになります。
PDF / TIFF リクエストからの出力は、指定した Cloud Storage バケットに作成された JSON ファイルに書き込まれます。
制限事項
Vision API は、2,000 ページまでの PDF/TIFF ファイルを受け入れます。これよりファイルが大きくなるとエラーが返されます。
認証
API キーは、files:asyncBatchAnnotate
リクエストではサポートされていません。サービス アカウントによる認証の手順については、サービス アカウントの使用をご覧ください。
認証に使用するアカウントは、出力のために指定する Cloud Storage バケットへのアクセス権(roles/editor
または roles/storage.objectCreator
以上)が付与されている必要があります。
API キーを使用してオペレーションのステータスをクエリできます。手順については、API キーの使用をご覧ください。
ドキュメント テキスト検出リクエスト
現在のところ、PDF や TIFF ドキュメントの検出は Cloud Storage バケットに保存されているファイルに対してのみ実行できます。レスポンスの JSON ファイルも Cloud Storage バケットに保存されます。
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
フィールドの代わりです。これには、次の 2 つの子フィールドが含まれます。gcsSource.uri
- PDF または TIFF ファイルの Google Cloud Storage URI(リクエストを行うユーザーまたはサービス アカウントがアクセス可能な URI)。mimeType
- 使用可能なファイルタイプのいずれか(application/pdf
またはimage/tiff
)。
outputConfig
は、出力の詳細を指定します。これには、次の 2 つの子フィールドが含まれます。gcsDestination.uri
- 有効な Google Cloud Storage URI。バケットは、リクエストを行うユーザーまたはサービス アカウントによって書き込み可能である必要があります。ファイル名はoutput-x-to-y
です。ここで、x
とy
は出力ファイルに含まれる PDF / TIFF のページ番号です。ファイルが存在する場合、その内容は上書きされます。batchSize
- それぞれの JSON 出力ファイルに含める出力ページ数を指定します。
HTTP メソッドと URL:
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 フィールドのみを含むレスポンスが返されます。
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
この name は関連 ID(例: 1efec2285bd442df
)を持つ長時間実行オペレーションの名前です。この名前は、v1.operations
API を使用してクエリできます。
Vision のアノテーション レスポンスを取得するには、v1.operations
エンドポイントに GET リクエストを送信し、URL でオペレーション 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) の JSON と似ていますが、指定された PDF または TIFF の場所とファイルのページ数を示す context
フィールドが追加されています。
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 は、リソースが特定のロケーションやリージョンに留まることを保証しません。ロケーションとして欧州連合を選択した場合、欧州連合でのみデータが保存され、処理されます。ユーザーはどこからでもデータにアクセスできます。
API を使用してロケーションを設定する
Vision API は、グローバル API エンドポイント(vision.googleapis.com
)と、2 つのリージョン ベースのエンドポイント(EU エンドポイント eu-vision.googleapis.com
と米国エンドポイント us-vision.googleapis.com
)をサポートしています。これらのエンドポイントはリージョン固有の処理に使用します。たとえば、EU でのみデータを保存して処理する場合は、REST API 呼び出しに vision.googleapis.com
ではなく URI eu-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 でのみデータを保存して処理するには、エンドポイント(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
フィールドの代わりです。これには、次の 2 つの子フィールドが含まれます。gcsSource.uri
- PDF または TIFF ファイルの Google Cloud Storage URI(リクエストを行うユーザーまたはサービス アカウントがアクセス可能な URI)。mimeType
- 使用可能なファイルタイプのいずれか(application/pdf
またはimage/tiff
)。
outputConfig
は、出力の詳細を指定します。これには、次の 2 つの子フィールドが含まれます。gcsDestination.uri
- 有効な Google Cloud Storage URI。バケットは、リクエストを行うユーザーまたはサービス アカウントによって書き込み可能である必要があります。ファイル名はoutput-x-to-y
です。ここで、x
とy
は出力ファイルに含まれる PDF / TIFF のページ番号です。ファイルが存在する場合、その内容は上書きされます。batchSize
- それぞれの JSON 出力ファイルに含める出力ページ数を指定します。
HTTP メソッドと URL:
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 フィールドのみを含むレスポンスが返されます。
{ "name": "projects/usable-auth-library/operations/1efec2285bd442df" }
この name は関連 ID(例: 1efec2285bd442df
)を持つ長時間実行オペレーションの名前です。この名前は、v1.operations
API を使用してクエリできます。
Vision のアノテーション レスポンスを取得するには、v1.operations
エンドポイントに GET リクエストを送信し、URL でオペレーション 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
機能を使用した場合はテキスト検出レスポンスに似ています。出力には、指定された PDF または TIFF の場所とファイルのページ数を示す context
フィールドが追加されています。
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 の無料トライアル