PDFテキスト化API仕様(暫定版)

​アップロードされたPDFファイルからテキストデータを抽出します。精度は2,3年かけて向上させます。

共通仕様

認証

 API キーによるトークン認証を行う。

 Authorization ヘッダーの Bearer スキームで渡された API キーがサインアップ済みアカウントに割り当てられた API キーであるかをチェックする。API キーが有効なものでない場合は 401 Unauthorized を返す。

 Authorization: Bearer {APIキー}

PDF アップロード

 受信した PDF ファイルをストレージに保存し、PDFTXT の前処理を開始する。

 本 API で PDF ファイルをアップロードした場合はテキスト取得 API の利用者とみなし、前処理のみを実行して処理を完了する。(アップロードした PDF に対する PDFTXT としての処理結果は作成しない。)

・メソッド POST
・URL   /api/books
・入力パラメータ(multipart/form-data)
 パラメータ名  型   説明

 file      File   PDFファイル
・レスポンス
 正常系
 200 OK で次のフィールド構造の JSON を返す。

 フィールド名  型   説明

 fileId     String  ファイル ID
 エラー系
 ステータス         説明
 400 Bad Request     入力パラメータに不正な値が指定された。
 403 Forbidden      月間の利用上限を超えている。

処理状態取得

 PDF の処理ステータスを返す。

・メソッド GET
・URL   /api/books/{fileId}
 パラメータ名    型      説明
 fileId       String    ファイル ID
・レスポンス
 正常系
 200 OK で次のフィールド構造の JSON を返す。

 フィールド名    型      説明
 status      Number    処理ステータス
 処理ステータス
  値    説明
  0    待機中
  1    データ抽出中
  2    データ解析中
  3    完了
  91    データ抽出時の異常終了
  92    データ解析時の異常終了
 エラー系
 ステータス    説明
 404 Not Found    fileIdに該当するファイルがない。またはfileIdが API キーに該当するユーザのアップロードしたファイルではない。

版面画像取得

 ページ版面の画像ファイル(png 形式)を返す。

・メソッド GET
・URL   /api/books/{fileId}/{pageNum}.png
 パラメータ名    型      説明
 fileId       String     ファイル ID
 pageNum    Number    ページ番号
・レスポンス
 ステータス       明
 200 OK        該当ページの版面画像を返す。
 404 Not Found    fileIdに該当するファイル、あるいはpageNumに該当するページがない。またはfileIdがAPIキーに該当するユーザのアップロードしたファイルではない。

テキスト取得

 該当ページの文字データを取得し、指定されたブロック内にある文字データだけで行を構成して返す。行は結合せず、版面の通りに物理改行して出力する。(段落化はしない)

 出力形式は HTML とし、body の内容にあたるテキストのみを返す。文字に振られているルビのみ ruby 要素で出力する。それ以外の装飾はしない。

・メソッド GET
・URL   /api/books/{fileId}/{pageNum}.txt
 パラメータ名    型      説明
 fileId       String    ファイル ID
 pageNum    Number    ページ番号
・クエリパラメータ
 取得対象のブロック(矩形)を指定する。指定の仕方は CSS の margin と同じ考え方である。例えば、left=0.1&top=0.1&right=0.1&bottom=0.1 とした場合は、版面の上下左右に 10%の余白をとった内部領域が取得の対象となる。

 パラメータ名   型     説明
 left      Number    矩形の左辺位置(版面の左端からの距離)を版面の幅に対する割合で指定する。省略時は 0
 top      Number    矩形の上辺位置(版面の上端からの距離)を版面の幅に対する割合で指定する。省略時は 0
 right      Number    矩形の右辺位置(版面の左端からの距離)を版面の幅に対する割合で指定する。省略時は 0
 bottom    Number    矩形の下辺位置(版面の下端からの距離)を版面の幅に対する割合で指定する。省略時は 0
・レスポンス
 ステータス        説明
 200 OK         HTML テキストを返す。
 400 Bad Request    入力パラメータに不正な値が指定された。
 404 Not Found     fileIdに該当するファイル、あるいはpageNumに該当するページがない。またはfileIdがAPIキーに該当するユーザのアップロードしたファイルではない。

版面画像取得

 ページ版面の画像ファイル(png 形式)を返す。

・メソッド GET
・URL   /api/books/{fileId}/{pageNum}.png
 パラメータ名    型      説明
 fileId       String    ファイル ID
 pageNum    Number    ページ番号
・レスポンス
 ステータス      説明
 200 OK        該当ページの版面画像を返す。
 404 Not Found    fileIdに該当するファイル、あるいはpageNumに該当するページがない。またはfileIdがAPIキーに該当するユーザのアップロードしたファイルではない。

処理結果受信

 テキスト化処理結果を受信する。完了ステータスが正常終了の場合は受信したファイルを Azure Storage に保存し、異常終了の場合はエラー内容を SQL Database に保存する。

・メソッド PUT
・URL   /api/books/{fileId}
 パラメータ名    型    説明
 fileId    String    ファイル ID
 入力パラメータ(multipart/form-data)
 パラメータ名    型      説明
 result       Boolean    処理結果。正常終了は true、異常終了は false を指定する。
 file        File      出力ファイル一式を ZIP 圧縮したファイル。正常終了の場合は必須。
 error       String     エラー内容。異常終了の場合は必須。
・レスポンス
 ステータス        説明
 200 OK         処理結果の受信に成功。
 400 Bad Request    入力パラメータに不正な値が指定された。
 404 Not Found     fileIdに該当するファイルがない。またはfileIdがAPIキーに該当するユーザのアップロードしたファイルではない。
 409 Conflict       該当ファイルの処理結果を既に受信済み。

PDF 削除

 アップロードした PDF ファイル、およびファイルから抽出してストレージ上に保存したファイルと処理結果のファイルを削除する。SQL Database 上のファイル情報は論理削除とする。

・メソッド DELETE
・URL   /api/books/{fileId}
 パラメータ名    型      説明
 fileId       String    ファイル ID
・レスポンス
 ステータス       説明
 200 OK        削除に成功。
 404 Not Found    fileIdに該当するファイルがない。またはfileIdが API キーに該当するユーザのアップロードしたファイルではない。