読者です 読者をやめる 読者になる 読者になる

FIELD NOTES: 書を持って街へ出よう

合同会社フィールドワークス プログラマ兼代表のブログ

PDF帳票を作成するためのWEB APIを提供開始しました

クラウド上のシステムからPDF帳票を作成するための実験的なサービス Field Reports for Cloud を提供開始しました。

このサービスで提供するField Reports APIを利用すれば,Google App Engine (GAE), Heroku, Salesforce.com (SFDC) などのPaaS上に構築されたシステムから,PDF帳票を作成することが可能になります。

Field Reports APIを利用するには,Field Reports for Cloud のサイト で利用者登録を行い,APIキーを取得する必要があります。

PDF帳票を作成する際には,JSON形式で記述したAPIパラメータ(レンダリング・パラメータ)を所定のURLにPOSTします。 リクエストの応答として,サーバ側で生成したPDFが返されます。

おおよそ以下2点の要件を満たす動作環境であれば,利用できるはずです。

  • 任意のJSON文字列を組み立てることができること。
  • 作成したJSON文字列を所定のURLへPOST(アップロード)できること。

このサービスは実験的な提供のため,現時点での利用料は無料です。

後述するようにトランザクション数などに制限を掛けてはいますが,Field Reports Standardの機能をほぼそのまま利用することができます。 トランザクション数がそれほど多くないシステムからであれば,かなり実用的に使うことができるのではないかと思います。

システム構成

実行環境としては,さくらVPSの2Gを利用しています。

使用している主なソフトウェアの構成は,以下のとおりです。

項目 ソフトウェア名
Webサーバ nginx
アプリケーションサーバ web2py
帳票ライブラリ Field Reports Standard for Linux


利用制限について

このサービスは,API呼び出し時のパラメータによりサーバに掛かる負荷が大きく変わります。 そこで,以下のような利用制限を設定しています。

  • 1日当たり(24時間以内)の呼び出し回数は,30件まで
  • 作成する帳票のページ数は,10ページまで

現在のところ,さくらVPS 2Gでまかなえる範囲内でこのサービスを運用していきたいと考えています。 サーバの負荷状況によっては,新規の利用者登録を停止したり上記の制限を変更する可能性があることを, あらかじめご了承願いたいと思います。

Hello World

コマンドラインツールのcurlを使って,APIを呼び出してみます。

まず,JSON形式のパラメータを作成してファイルに保存します(ファイル名:hello.json)。 <APIキー>の部分には,取得したAPIキーを記入します。

{
    "settings": {
        "api-key": <APIキー>
    },
    "template": {"paper": "A4"},
    "context": {
        "hello_1": {
            "new": "Tx",
            "value": "Hello, World!",
            "rect": [100, 700, 400, 750],
            "font": "/Times-Roman"
        },
        "hello_2": {
            "new": "Tx",
            "value": "Hello, World!",
            "rect": [100, 600, 400, 650],
            "font": "/Helvetica-Oblique"
        },
        "hello_3": {
            "new": "Tx",
            "value": "Hello, World!",
            "rect": [100, 500, 400, 550],
            "font": "/Courier-Bold"
        },
        "hello_4": {
            "new": "Tx",
            "value": "ABCDEFGHIJKLMN",
            "rect": [100, 400, 400, 450],
            "font": "/ZapfDingbats"
        },
        "hello_5": {
            "new": "Tx",
            "value": "こんにちは世界",
            "rect": [100, 300, 400, 350],
            "font": "/KozGo-Medium"
        }
    }
}

hello.jsonがカレンドディレクトリに存在する状態で,以下のようにcurlコマンドを実行します。

$ curl -k https://labs.field-works.co.jp/webapi/render --data @hello.json -o hello.pdf

成功すれば,以下のようなPDFが作成されます。

テンプレートを利用した帳票作成

本格的な帳票の作成には,テンプレートの利用が必須になります。

Field Reports ではテンプレートをPDF形式で作成しますが, 作成したテンプレートファイルを何らかの方法でサーバに送り込む必要があります。

それには,以下の3種類の方法が考えられます。

  1. Field Reports for Cloud サーバ上に置き,ローカルパスを指定する。
  2. 利用者側が準備したサーバ上に置き,URLを指定する。
  3. data URI scheme文字列として,レンダリングパラメータにインラインで埋め込む。

現在のところ,利用者が任意のファイルをField Reports for Cloud サーバ上に置くことを許可していませんので, 1の方法で利用できるのは,前もって準備してある数種類のサンプルのみです。

2の方法を取る場合は,以下のようにテンプレートの場所を指示します。

"template": {"src": "http://example.com/template.pdf"}

3の方法を取る場合は,テンプレートファイルをBase64エンコードした上で,レンダリングパラメータに埋め込みます。

"template": {"src": "data:application/pdf;base64,AAAoAAAARgAAAMD....."}

同様に,画像ファイルやフォントファイルなどもURLかdata URI scheme文字列で指定することができます。