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

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

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

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

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

そのためには、skills リソースに GET リクエストを送信します。次のコマンドを実行します：レスポンスには、次のような 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 リクエストを送信します。次のコマンドを実行します：空のトランザクションが正常に作成されると、トランザクション識別子を含むレスポンスが返されます。

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

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

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

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

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

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

その場合は、POST リクエストを transactions/<transaction-id>/files リソースに送信します。次のコマンドを実行します：その結果、追加されたファイルとその識別子の一覧を含むレスポンスが返ってきます。この呼び出しを複数回繰り返すことで、必要な数だけファイルを追加できます。ファイルのアップロードに関する追加オプション:

Document にファイルを追加する

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

トランザクションの開始

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

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

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

{
   "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"
      }
   ]
}

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

status キーの値が次のいずれかに設定されている場合:
- New — トランザクションは作成されていますが、現在は処理中ではありません。
- Processing — トランザクションは開始されていますが、結果はまだ準備できていません。
- Processed — トランザクションは正常に完了しており、結果をダウンロードできます。
- Failed — トランザクションは失敗しました。
- Canceled — トランザクションはキャンセルされました。
manualReviewLink キーには、手動確認が必要な場合、手動確認クライアントのWebインターフェイスへのリンクとVantage access token が含まれます。このリンクとトークンを使用すると、特定のトランザクションの分類および 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 配列では、各 documents に resultFiles 配列があります。fileId の値を取得するには、この配列を使用します。出力ファイルの形式は、使用する Skill によって決まります。現在、すべての Skill は抽出されたフィールドを JSON 形式で返します。分類スキルの場合、documents が処理された後に返されるレスポンスは、次のようになります。

{
   "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status": "Processed",
   "documents": [
      {
         "id": "9838448d-72ae-4e9a-b071-2bb16f732e46",
         "classification": {
            "isResultClassConfident": true,
            "resultClass": "Invoice",
            "classConfidences": [
               {
                  "class": "Invoice",
                  "confidence": 89
               },
               {
                  "class": "PurchaseOrder",
                  "confidence": 32
               }
            ]
         }
      }
   ],
   "sourceFiles": [
      {
         "id": "7b2eed6f-3fdd-43b9-a178-7211d0a8d5bb",
         "name": "Invoice07.jpg"
      }
   ]
}

Document のクラスを resultClass キーから取得し、各候補クラスの信頼度を confidence キーで確認します。 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 リクエストを送信し、トランザクションの識別子を指定します。その結果、このトランザクション内で作成された documents の一覧が返されます。レスポンスにはこれらの documents の識別子も含まれており、特定の documents の詳細情報を取得する際に必要になる場合があります。

ソースファイル

必要なソースファイルをダウンロードするには、transactions/<transaction-id>/documents/<document-id>/sourceFiles/<file-id>/download リソースに GET リクエストを送信し、トランザクション、Document、ファイルの識別子 (直前のレスポンスから取得) を指定します。次のコマンドを実行します。レスポンスにはファイルがバイナリ形式で含まれます。すべてのソースファイルに対してこの手順を繰り返します。

結果ファイル

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

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

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

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

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

​Document にファイルを追加する

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

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

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

​ソースファイル

​結果ファイル

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

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

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

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

Document にファイルを追加する

トランザクションの開始

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

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

ソースファイル

結果ファイル