Web-API 解説

« リクエスタ | fusion_place 実行環境 »

This page is in Japanese version. The English version is in preparation.

Web-API とは

[Web-API] とは、fusion_place の機能を使用するプログラムを開発するための、アプリケーション・プログラム・インターフェース（API）です。[Web-API] は HTTP プロトコルベースですので、開発言語を問わず、多様なプログラムから使用することができます。

なお、[Web-API] に関する以下の解説は、HTTP プロトコルに関する基本的知識を前提としています。

Web-API でできること

[Web-API] では、以下の通り、リクエスタと同様の処理を実行することができます。

[Web-API] でのリクエストの書式は、リクエスタのリクエストファイルの書式とほとんど同じです。実際、リクエスタは、リクエストを fusion_place に送信し、レスポンスを受信するために、[Web-API] を使用しています。

Web-API の使用可能環境

fusion_place のサーバ上でなくとも、fusion_place サーバに URL でアクセスできるコンピュータ上 ^[1] であれば、[Web-API] を介して fusion_place サーバでの処理を実行することができます。

(fusion_place < 14.0) [Web-API] では、セッション情報のやり取りに Cookie を使いますので、クライアント側は Cookie を受け入れ可能でなければなりません。

Web-API の呼び出し方法

[Web-API] を使うには、fusion_place の API 用 URL に、XML 形式テキストデータとして、リクエスト内容を POST します。そうすると、依頼された処理をサーバが実行し、処理結果（レスポンス）が同じく XML 形式テキストデータとして返されます。

API 用 URL

fusion_place のサーバの URL の末尾に、/api/1.2/requests を追加したものが、API 用の URL です。例えば fusion_place のサーバの URL が、http://localhost:50000/fusionplace ならば、API 用 URL は以下の通りです。

http://localhost:50000/fusionplace/api/1.2/requests

認証(fusion_place >= 14.0)

[Web-API] の HTTP アクセスは Bearer 認証を用いて行います。アクセストークン( ACCESS_TOKEN )を事前に取得し、HTTPヘッダに下記のように Authorization ヘッダを付与してください。

Authorization: bearer <ACCESS_TOKEN>

アクセストークンの取得方法

まずは、クライアント登録を行い、クライアントクレデンシャル( CLIENT_CREDENTIALS )を取得します。

URL

http://localhost:50000/fusionplace/rest/v1/oauth/client

メソッド

POST

ヘッダ

Content-Type: "application/json"

ボディ

{
    "grant_types": ["password", "refresh_token"],
    "scope": "webapi",
    "client_name": "<CLIENT_NAME>"
}

<CLIENT_NAME> は [Web-API] を利用するクライアントの名前を指定します。

レスポンス

 {
    "grant_types": [
      "password",
      "refresh_token"
    ],
    "client_secret_expires_at": "1718069506982",
    "scope": "webapi",
    "client_secret": "kb6WPe5XLvo6rX81btvx",
    "client_id_issued_at": "1717983106982",
    "client_name": "curl",
    "token_endpoint_auth_method": "client_secret_basic",
    "client_id": "8447d19d-5006-41d8-bb8d-9a0150c84b22",
}

client_id と client_secret の値をコロンで連結し、Base64エンコードしたものが後続処理の認証ヘッダの CLIENT_CREDENTIALS になります。

次に、取得したクライアントクレデンシャルを用いてアクセストークンを取得します。

URL

http://localhost:50000/fusionplace/rest/v1/oauth/token

メソッド

POST

ヘッダ

Content-Type: "application/x-www-form-urlencoded"
Authorization: "Basic <CLIENT_CREDENTIALS>"

<CLIENT_CREDENTIALS> は取得したクライアントクレデンシャルを指定します。

ボディ

username=<USER_NAME>&password=<PASSWORD>&grant_type=password&scope=webapi

<USER_NAME> はユーザアカウント名、<PASSWORD> はパスワードを指定します。

レスポンス

 {
    "access_token": "AKcmWdbpeX75AZi",
    "refresh_token": "3ZzboNpzcmBUrLU",
    "scope": "webapi",
    "token_type": "Bearer"
}

access_token の値がアクセストークンです。 refresh_token の値がリフレッシュトークンで、アクセストークンの有効期限が切れた場合の再取得に使います。

注意事項

アクセストークンは有効期限がありますので、有効期限が切れると再取得する必要があります。

URL

http://localhost:50000/fusionplace/rest/v1/oauth/token

メソッド

POST

ヘッダ

Content-Type: "application/x-www-form-urlencoded"
Authorization: "Basic <CLIENT_CREDENTIALS>"

<CLIENT_CREDENTIALS> は取得したクライアントクレデンシャルを指定します。

ボディ

refresh_token=<REFRESH_TOKEN>&grant_type=refresh_token

<REFRESH_TOKEN> は取得したリフレッシュトークンを指定します。

レスポンス

 {
    "access_token": "QJB874KGFybPNfD",
    "refresh_token": "1NpHLSSFCwruIlW",
    "scope": "webapi",
    "token_type": "Bearer"
}

アクセストークンは使い終わったら、明示的に終了してください。

URL

http://localhost:50000/fusionplace/rest/v1/process/terminate

メソッド

POST

ヘッダ

Content-Type: "application/x-www-form-urlencoded"
Authorization: "Basic <CLIENT_CREDENTIALS>"

<CLIENT_CREDENTIALS> は取得したクライアントクレデンシャルを指定します。

ボディ

token=<ACCESS_TOKEN>

<ACCESS_TOKEN> は取得したアクセストークンを指定します。

レスポンス

認証(fusion_place < 14.0)

WWW-Authenticate: Digest realm="FusionPlace System",qop="auth",nonce="978cfd86321e50711213062f4573b9e7"

[Web-API] の HTTP アクセスにおいては、[ブラウザ] 等のクライアントプログラムと同様に、fusion_place サーバに設定された認証方式（デフォルト: Digest 認証 ^[2]）が用いられます。したがって、[Web-API] を使用して fusion_place サーバに処理を依頼するクライアントプログラムは、設定された認証方式に対応している必要があります。多くのプログラミング言語で、Digest 認証（または Basic 認証）に容易に対応できるようなライブラリが提供されています。

Digest 認証 / Basic 認証では、ユーザ管理の範囲を表すために「レルム（Realm）」を用います。fusion_place のレルムは FusionPlace System です。

なお、[Web-API] は、fusion_place 使用権許諾契約書で定義される「クライアントプログラム」のひとつです。従って、ひとつのユーザアカウントを用いてひとつのクライアントプログラムで運用できるセッション（ログイン以降ログアウトまたはクライアントプログラム終了までの業務）の数はひとつに限られるという、使用権許諾契約約款又は利用規約中の規定は、[Web-API] にも適用されます。

HTTP メソッド

HTTP メソッド（HTTP プロトコルを用いてサーバに処理やデータを依頼する際の命令文）には、GET, PUT, POST などがありますが、fusion_place の [Web-API] では、必ず、POST を用いて下さい。

HTTP リクエスト（通常のリクエスト）

リクエストヘッダ

必要に応じて以下の HTTP ヘッダを設定して下さい。

HTTP ヘッダ必須説明

HTTP ヘッダ	必須	説明
Content-Type	No	指定する場合、`appplication/xml` として下さい。
Content-Encoding	No	指定する場合、`gzip` として下さい。その場合、リクエストボディは gzip 圧縮して下さい。
Accept-Encoding	No	指定する場合、`gzip` として下さい。その場合、リクエストボディは gzip 圧縮して返却されます。
Accept-Language	No	レスポンスの言語。日本語なら `ja`、英語なら `en` と指定します。2 つ以上指定した場合、2 つ目以降は無視されます。指定しなければサーバのデフォルト言語が適用されます。上記ルールで決まる言語が、日本語、英語以外ならば、英語に置換されます。
Accept-Charset	No	レスポンスに適用する文字集合。2 つ以上指定した場合、2 つ目以降は無視されます。指定しなければ、`UTF-8` が適用されます。
Authorization (fusion_place >= 14.0)	Yes	アクセストークンを事前に取得し、`Bearer <ACCESS_TOKEN>` として下さい。

Content-Type

指定する場合、appplication/xml として下さい。

Content-Encoding

指定する場合、gzip として下さい。その場合、リクエストボディは gzip 圧縮して下さい。

Accept-Encoding

指定する場合、gzip として下さい。その場合、リクエストボディは gzip 圧縮して返却されます。

Accept-Language

レスポンスの言語。日本語なら ja、英語なら en と指定します。2 つ以上指定した場合、2 つ目以降は無視されます。指定しなければサーバのデフォルト言語が適用されます。

上記ルールで決まる言語が、日本語、英語以外ならば、英語に置換されます。

Accept-Charset

レスポンスに適用する文字集合。2 つ以上指定した場合、2 つ目以降は無視されます。指定しなければ、UTF-8 が適用されます。

Authorization
(fusion_place >= 14.0)

Yes

アクセストークンを事前に取得し、Bearer <ACCESS_TOKEN> として下さい。

リクエストボディ

リクエストボディの内容は以下のようなテキストデータです。

<?xml version="1.0" encoding="Windows-31J"?> (1)
<request type="IMPORT_VALUES" desc="実績インポートA"> (2)
  <!-- ... -->
</request> (3)

1	XML 宣言
2	「リクエスト」開始
3	「リクエスト」終了

リクエスタを使用する場合のリクエストファイルの記述形式と似ていますが、以下の違いがあります。

リクエスタの場合は、ひとつのリクエストファイル中に複数のリクエストを含めることができますが、[Web-API] では、一回の HTTP リクエストに含めることができるリクエスト（request タグで囲まれた範囲）はひとつに限られます。また、そのため、[Web-API] では全体を囲む resuests タグは使用されません。
リクエスタで使用できる環境変数値の埋め込みおよびエクスターナルモードは、[Web-API] では使用できません。

上記の相違点を除いて、リクエスタを使用する場合のリクエストファイルとまったく同様に記述して下さい。

HTTP リクエスト（セッション確立用のリクエスト）

リクエスト送信に先立って、認証を済ませ、セッションを確立したい場合があります。このようなニーズが生じるのは、典型的には、HTTP/1.1 で導入された「Chunked transfer encoding （CTE）」を用いてデータ送信したい場合です。

CTE を適用すると、送信するデータの長さを HTTP ヘッダ（Content-Length）に設定する必要がないため長大なデータを送信するのに便利ですが、一部のクライアントは、CTE を適用した場合には認証に対応していません（例えば、Java のクライアントサイド API である HttpUrlConnection）。

そのような場合、ここでご説明するリクエストボディを含むリクエストを CTE を適用しないで送信し、その後、CTE を適用して通常のリクエストを送信します。そのようにすると最初のリクエスト送信時に認証が行われますので、後続の CTE でのリクエスト送信時は認証を回避することができます。

リクエストヘッダ

（通常のリクエストの場合と同じです）

リクエストボディ

リクエストボディの内容は以下のようなテキストデータです。

<?xml version="1.0" encoding="Windows-31J"?> (1)
<connect/>

XML 宣言

HTTP レスポンス

HTTP ステータスコード

処理結果に応じて、標準に即した HTTP レスポンスコードが返されます。例えば、サーバとの通信に支障が無かった場合、レスポンスコードとして 200 OK が返されます。200 OK の意味に注意して下さい。これはサーバとの通信に関して支障が無かったことを示しているだけであり、サーバ側でエラーや警告なくリクエストを処理できたことを意味するものではありません。リクエストの処理に成功したかどうかを知るには、レスポンスボディ中の「処理結果コード」を検査する必要があります。

レスポンスボディ

セッション確立用のリクエストに対するレスポンスの場合、レスポンスボディはありません。

通常のリクエストに対するレスポンスボディの内容は以下のようなテキストデータです。

<?xml version="1.0" encoding="Windows-31J"?> (1)
<response type="IMPORT_VALUES" desc="実績インポートA"> (2)
  <!-- ... -->
</response> (3)

1	XML 宣言
2	「レスポンス」開始
3	「レスポンス」終了

リクエストボディの場合と同様に、一回の HTTP レスポンスに含まれるレスポンス（response タグで囲まれた範囲）はひとつだけです。そのため、[Web-API] では全体を囲む responses タグは使用されません。

上記の相違点を除いて、リクエスタを使用した場合のレスポンスファイルとまったく同じ規則が適用されます。

1. fusion_place マネージャ/ブラウザや Excel-Link を用いて fusion_place サーバに接続できるコンピュータのことです。

2. シングルサインオン（LDAP）利用時の認証方式は Basic 認証になります。