個別の API コールで documents を処理する

トランザクションの作成、ファイルのアップロード、トランザクションの開始など、個別の API コールを使用して documents を処理する一般的なシナリオは、次の手順で構成されます。

利用可能なすべての Skill の一覧を取得する
空のトランザクションを作成する
トランザクション内で処理するファイルのセットを追加する
トランザクションを開始する
トランザクションのステータスを監視する
ソースファイルと結果ファイルをダウンロードする

各リクエストには、アクセストークンなどの認証情報を必ず含める必要があります。詳細については、認証を参照してください。

利用可能なすべての Skill の一覧を取得する

そのためには、skills リソースに GET リクエストを送信します。

GET https://vantage-us.abbyy.com/api/publicapi/v1/skills

GET https://vantage-eu.abbyy.com/api/publicapi/v1/skills

GET https://vantage-au.abbyy.com/api/publicapi/v1/skills

次のコマンドを実行します：

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/skills" \
-H "Authorization: Bearer token"

レスポンスには、次のような JSON が含まれます：

[
   {
      "id": "Receipt",
      "name": "Receipt",
      "type": "Document"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "NewClassifier",
      "type": "Classification"
   },
   {
      "id": "c4b26798-07cb-11eb-adc1-0242ac120002",
      "name": "Invoice",
      "type": "Document"
   }
]

使用する Skill 識別子を指定します。Skill の詳細な説明は、組み込み Skill に記載されています。

空のトランザクションを作成する

空のトランザクションを作成するには、transactions リソースに次の POST リクエストを送信します。

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions

次のコマンドを実行します。

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d "{\"skillId\":\"123\"}"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d "{\"skillId\":\"123\"}"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d "{\"skillId\":\"123\"}"

空のトランザクションが正常に作成されると、トランザクション識別子を含むレスポンスが返されます。

{
   "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

トランザクションで処理するファイルセットの追加

1 つのトランザクションに含められるファイルの最大数は 1000 件です。

ファイルセットの追加方法は次の 2 通りです:

トランザクションへ直接追加
Document に追加してから、その Document をトランザクションに追加

トランザクションにファイルを直接追加する

その場合は、POST リクエストを transactions/<transaction-id>/files リソースに送信します。

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files

リクエストの本文に処理対象のファイルを送信します。ファイルのカスタマイズに使用できる Parameter の詳細は、お使いのリージョンの Swagger API reference を参照してください: US、EU、または AU。次のコマンドを実行します：

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

成功すると、サーバーは空のレスポンス本文とともに HTTP 200 を返します。追加されたファイルとその識別子を確認するには、GET transactions/<transaction-id>/documents をリクエストします。この呼び出しを複数回繰り返すことで、必要な数だけファイルを追加できます。ただし、トランザクション内の各ファイル名は一意である必要があります (同じ名前のファイルを追加すると HTTP 409 が返されます) 。ファイルのアップロードに関する追加オプション:

文書へのファイルの追加

まず、transactions/<transaction-id>/documents リソースに POST リクエストを送信して文書を作成します。

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json-patch+json"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json-patch+json"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json-patch+json"

文書識別子を含むレスポンスが返されます。次に、transactions/<transaction-id>/documents/<document-id>/sourceFiles リソースに POST リクエストを送信して、文書にファイルを追加します。

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/" \
-H "Authorization: Bearer token" \
-F "Files=@Invoice07.jpg; type=image/jpeg"

トランザクションの開始

指定したSkillとファイルでトランザクションを開始するには、transactions/<transaction-id>/start リソースに次の POST リクエストを送信します。

POST https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start

POST https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/start

POST https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/start

curl -X POST "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-d ""

curl -X POST "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-d ""

curl -X POST "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/start" \
-H "accept: */*" \
-H "Authorization: Bearer token" \
-d ""

トランザクションのステータスを監視する

短いタイムアウトを設定したループでトランザクションのステータス監視を開始するには (1秒より高頻度の確認は推奨しません) 、リクエストURIにトランザクション識別子を含めて transactions/<transaction_id> リソースへ GET リクエストを送信します。

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id" \
-H "Authorization: Bearer token"

レスポンスは次のようになります。

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-us.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-eu.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processing", 
   "manualReviewLink": "https://vantage-au.abbyy.com/api/publicapi/v1/verify?documentIds=9838448d-72ae-4e9a-b071-2bb16f732e46",
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.JPG"
      }
   ]
}

レスポンスでは、次のようになります。

status キーの値が次のいずれかに設定されている場合:
- New — トランザクションは作成されていますが、現在は処理中ではありません。
- Processing — トランザクションは開始されていますが、結果はまだ準備できていません。
- Processed — トランザクションは正常に完了しており、結果をダウンロードできます。
- Failed — トランザクションは失敗しました。
- Canceled — トランザクションはキャンセルされました。
manualReviewLink キーには、手動確認が必要な場合、手動確認クライアントのWebインターフェイスへのリンクとVantage アクセストークンが含まれます。このリンクとトークンを使用すると、特定のトランザクションの分類および field extraction の結果を確認し、修正できます。確認が完了するまで、status キーの値は Processing に設定されます。提供されたリンクは 168 時間有効です。有効期限が切れた場合は、同じ方法で新しいリンクを作成して取得し、さらに 168 時間利用する必要があります。詳しくは、手動確認の統合を参照してください。

このリンクを使用して認証されたユーザーは、他の documents やトランザクションを表示または変更できません。

documents skill の場合、レスポンスは次のようになります。

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "resultFiles": [
            {
               "fileId": "3a3e6245-48e1-489a-9fef-a10b5ba28515",
               "type": "Json"
            }
         ],
         "businessRulesErrors": []
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

documents 配列では、各ドキュメントに resultFiles 配列が含まれています。この配列を使用して fileId の値を取得します。出力ファイルの形式は、使用する Skill によって定義されます。現在、すべての Skill は抽出されたフィールドを JSON 形式で返します。分類スキルの場合、ドキュメントの処理後に受信するレスポンスは次のようになります。

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": {
               "id": "8f2a51d4-6c0b-4e2a-9d3e-5b7c1a9f0e64",
               "name": "Invoice"
            },
            "classConfidences": [
               {
                  "classId": "8f2a51d4-6c0b-4e2a-9d3e-5b7c1a9f0e64",
                  "className": "Invoice",
                  "confidence": 89
               },
               {
                  "classId": "2c9d7e01-4b3a-4f6c-8a15-d0e6f2b8c473",
                  "className": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

Document のクラスを resultClass.name キーから取得し、各候補クラスの信頼度を confidence キーで確認します (0～100 の整数) 。 Process skill の場合、レスポンスには、Process skill で利用可能なステージに応じて、Document および分類スキルで返される情報の全部または一部が含まれることがあります。

ソースファイルと結果ファイルのダウンロード

処理が完了すると、2 種類のファイルをダウンロードできます。

ソースファイル — アップロードした元のファイルで、元のバイナリ形式のまま返されます。
結果ファイル — 処理結果の出力ファイルです。既定では、抽出データが JSON 形式で返されます (出力形式は Skill で設定されます) 。

ソースファイルと結果ファイルでは、使用するエンドポイントとファイル識別子が異なります。

ソースファイル — GET transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download。ファイル ID は GET transactions/<transaction-id>/documents のレスポンス (sourceFiles[].id) から取得します。
結果ファイル — GET transactions/<transaction-id>/files/<file-id>/download。ファイル ID はトランザクションのステータスのレスポンス内の resultFiles 配列 (documents[].resultFiles[].fileId) から取得します。

documents の識別子を含む一覧を取得するには、transactions/<transaction-id>/documents リソースに GET リクエストを送信し、トランザクションの識別子を指定します。

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents" \
-H "Authorization: Bearer token"

その結果、このトランザクション内で作成された documents の一覧が返されます。レスポンスにはこれらの documents の識別子も含まれており、特定の documents の詳細情報を取得する際に必要になる場合があります。

ソースファイル

必要なソースファイルをダウンロードするには、transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download リソースに GET リクエストを送信し、トランザクション、ドキュメント、ファイルの識別子 (直前のレスポンスで取得) を指定します。

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download

次のコマンドを実行します。

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/documents/document-id/sourceFiles/file-id/download" \
-H "Authorization: Bearer token"

レスポンスには、バイナリ形式のファイルが含まれます。すべてのソースファイルに対して、この手順を繰り返します。

結果ファイル

結果ファイルをダウンロードするには、transactions/<transaction-id>/files/<file-id>/download リソースに GET リクエストを送信し、トランザクション識別子と結果ファイルの fileId を指定します。fileId は、トランザクションのステータスを監視した際に返される resultFiles 配列から取得します (各エントリには fileId と、Json などの type が含まれます)。

GET https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download

GET https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download

GET https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download

次のコマンドを実行します。

curl -X GET "https://vantage-us.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-eu.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
-H "Authorization: Bearer token"

curl -X GET "https://vantage-au.abbyy.com/api/publicapi/v1/transactions/transaction-id/files/file-id/download" \
-H "Authorization: Bearer token"

概要

開発者ガイド

個別の API コールで documents を処理する

利用可能なすべての Skill の一覧を取得する

空のトランザクションを作成する

トランザクションで処理するファイルセットの追加

トランザクションにファイルを直接追加する

文書へのファイルの追加

トランザクションの開始

トランザクションのステータスを監視する

ソースファイルと結果ファイルのダウンロード

ソースファイル

結果ファイル

​利用可能なすべての Skill の一覧を取得する

​空のトランザクションを作成する

​トランザクションで処理するファイルセットの追加

​トランザクションにファイルを直接追加する

​文書へのファイルの追加

​トランザクションの開始

​トランザクションのステータスを監視する

​ソースファイルと結果ファイルのダウンロード

​ソースファイル

​結果ファイル

利用可能なすべての Skill の一覧を取得する

空のトランザクションを作成する

トランザクションで処理するファイルセットの追加

トランザクションにファイルを直接追加する

文書へのファイルの追加

トランザクションの開始

トランザクションのステータスを監視する

ソースファイルと結果ファイルのダウンロード

ソースファイル

結果ファイル