基本的な呼び出し規約
本サービスの WebAPI は、HTML のフォームを application/x-www-form-urlencoded もしくは multipart/form-data でエンコードし、HTTPS POST した場合と同じ形式で呼び出してください。
バイナリデータを POST する場合には multipart/form-data を使用してください。
HTMLフォームサンプル
<form method="POST" enctype="multipart/form-data">...</form>
クライアントの認証
クライアントの認証は、本サービス上で発行した WebAPIキー を用いて行います。
Cookie や BASIC 認証などの認証メカニズムを使用せず、簡易なコーディングで API を利用できます。
WebAPIキーの発行箇所
システムの管理 ＞ 連携アプリの設定 ＞ WebAPIキーの管理
注意事項
WebAPI による操作は強力な権限を持っています。
WebAPIキーが信頼できない第三者に漏れることがないよう管理してください。
キーの有効期限や呼び出し可能な IP アドレス、利用可能な API を最小限に設定するなど、制限をかけてご利用ください。
APIの呼び出し結果
WebAPI の呼び出しが成功した場合、結果は XML形式の HTTP レスポンス として返されます。
共通レスポンスとして、XPath の表現で //response/result にリザルトコードが返されます。
呼び出し自体が失敗した場合には、HTTPS ステータスコードのエラー値が返されます。
補足事項
一部の API は CSV、JSON 形式でレスポンスが返ります。API の詳細を確認してください。
リザルトコード
| リザルトコード | 説明 |
|---|---|
| 1 | API呼び出しが成功したことを表し、全てのトランザクションは成功してコミットが完了した状態です。より詳細な結果は API 呼び出しごとに XML 内に返されます。クライアントは XML から詳細結果を取得できます。 |
| 1以外 | API呼び出しが失敗したことを表し、全てのトランザクションはロールバックされ、呼び出し前の状態に戻ります。すべての API でテキスト形式のエラーメッセージが返されます。クライアントはエラーログに記録するなど適切な対応が必要です。 |
HTTPSステータスコード
| コード | 説明 |
|---|---|
| 400 BAD REQUEST | 操作対象のパラメータが不正な場合に返されます。パラメータや指定方法を確認してください。 |
| 403 FORBIDDEN | アクセスが許可されていない場合に返されます。WebAPIキーの有効期限や、指定した IP アドレスから呼び出しているか確認してください。 |
| 404 NOT FOUND | URL または WebAPIキーが正しくない場合に返されます。指定内容を確認してください。 |
| 503 SERVICE UNAVAILABLE | API の繰り返し呼び出しなどで上限に達した場合に返されます。少し時間をおいて再度呼び出してください。 |
APIの呼び出しに関する制限
API を短時間に大量呼び出しすると、システムに過大な負荷がかかり、パフォーマンスに影響を及ぼす可能性があります。
そのため一部の API を除き、一定時間内に呼び出し可能な回数を、システム負荷に応じて 1分間あたり 12〜60 回 に制限しています。
また、サービス提供時間外の呼び出しは、緊急メンテナンスのため予告なく停止する場合があります。
利用可能なタイムゾーン
本 API で利用可能なタイムゾーン ID は以下の通りです。
| タイムゾーンID | 説明 |
|---|---|
| America/Juneau | US アラスカ標準時 -08:00 |
| PST8PDT | US 太平洋標準時 -08:00 |
| MST7MDT | US 山地標準時 -07:00 |
| CST6CDT | US 中部標準時 -06:00 |
| EST5EDT | US 東部標準時 -05:00 |
| Europe/London | UK |
| WET | 西ヨーロッパ時間 |
| CET | 中部ヨーロッパ時間 +01:00 |
| EET | 東ヨーロッパ時間 +02:00 |
| Europe/Moscow | ロシア（モスクワ） +03:00 |
| Asia/Yekaterinburg | ロシア（エカテリンブルグ） +05:00 |
| Asia/Calcutta | インド標準時 +05:30 |
| Asia/Omsk | ロシア（オムスク） +07:00 |
| Asia/Bangkok | タイ +07:00 |
| Asia/Jakarta | インドネシア +07:00 |
| Asia/Krasnoyarsk | ロシア（クラスノヤルスク） +08:00 |
| Asia/Manila | フィリピン +08:00 |
| Asia/Kuala_Lumpur | マレーシア +08:00 |
| Asia/Singapore | シンガポール +08:00 |
| Asia/Shanghai | 中国標準時 +08:00 |
| Asia/Hong_Kong | 香港 +08:00 |
| Asia/Macau | マカオ +08:00 |
| Asia/Taipei | 台湾 +08:00 |
| Australia/Perth | オーストラリア西部 +08:00 |
| Asia/Irkutsk | ロシア（イルクーツク） +09:00 |
| Asia/Tokyo | 日本 +09:00 |
| Asia/Seoul | 韓国 +09:00 |
| Australia/Adelaide | オーストラリア中部 +09:30 |
| Australia/Sydney | オーストラリア東部 +10:00 |
| Asia/Yakutsk | ロシア（ヤクーツク） +10:00 |
| Asia/Vladivostok | ロシア（ウラジオストック） +11:00 |
| Asia/Magadan | ロシア（マガダン） +12:00 |
HTMLによるAPI呼び出し例
HTML フォームから書庫に文書を登録する API を呼び出す例です。
HTMLコード
01: <html>
02: <head>
03: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
04: <title>書庫登録APIの呼び出しサンプル</title>
05: </head>
06: <body>
07: <form method="POST"
08: action="https://{your-domain}/h2/STRLibraryManipurator.do"
09: enctype="multipart/form-data">
10: <input type="hidden" name="func" value="create" />
11: <input type="hidden" name="key" value="Y70L-T6TJ-E2O8-XHLZ-BPQ9-8VG3-7XVU-O1D8" />
12: <div>タイトル: <input type="text" name="title" /></div>
13: <div>ファイル: <input type="file" name="file" /></div>
14: <input type="submit" value="送信" />
15: </form>
16: </body>
17: </html>
HTMLコードの説明
- 03行目：文字コードに UTF-8 を指定しています。
- 07行目：呼び出しメソッドを POST に指定しています。
- 08行目：呼び出し先 URL を指定しています。
{your-domain}は利用環境に合わせて変更してください。{}は不要です。 - 09行目：ファイルアップロードのため、
multipart/form-dataエンコーディングを指定しています。 - 10行目：書庫文書の登録 API 呼び出しを指定しています。
- 11行目：WebAPIキーを指定しています。
valueの値を、発行した WebAPIキーに変更してください。 - 12行目：登録する書庫文書タイトルの入力フォームです。
- 13行目：登録するファイルの選択フォームです。
- 14行目：フォーム送信ボタンです。
この HTML コードを UTF-8 で保存してブラウザで開くと、タイトル入力とファイル選択後に「送信」ボタンから WebAPI を呼び出せます。
呼び出しが成功するとレスポンス XML が表示され、//response/result が 1 の場合は成功です。//response/doc-id に登録された文書IDが返されます。
bash + wget によるAPI呼び出し例
Unix系OS のシェルスクリプトから bash と wget を利用して、書庫に文書を登録する API を呼び出す例です。
wget は HTML フォームの POST データ組み立て機能を持たないため、まず bash で multipart/form-data 形式のデータを作成し、それを wget で送信します。
実行例
$ sample.sh {書庫文書のタイトル} {アップロードするファイルのパス}sample.sh
01: #!/bin/bash
02: export DATESTR=`LANG=C date`
03: export TODAY=$(date +%Y%m%d%H%M%S --date="$DATESTR")
04: export BOUNDARY="$TODAY"
05:
06: export TMPFILE="/tmp/$BOUNDARY.dat"
07:
08: ## multipart/form-data として文字列のパラメータをひとつ追加する
09: append_param() {
10: echo -e -n "--$BOUNDARY\r\n" >> $TMPFILE
11: echo -e -n "Content-Disposition: form-data; name=\"$1\"\r\n" >> $TMPFILE
12: echo -e -n "\r\n" >> $TMPFILE
13: echo -e -n "$2\r\n" >> $TMPFILE
14: }
15:
16: trap "rm -f $TMPFILE" INT
17:
18: append_param "func" "create"
19: append_param "key" "Y70L-T6TJ-E2O8-XHLZ-BPQ9-8VG3-7XVU-O1D8"
20: append_param "title" "$1"
21:
22: ## ファイルの中身を Content-Transfer-Encoding: binary で追加する
23: echo -e -n "--$BOUNDARY\r\n" >> $TMPFILE
24: echo -e -n "Content-Disposition: form-data; name=\"file\"; filename=\"$2\"\r\n" >> $TMPFILE
25: echo -e -n "Content-type: application/octet-stream\r\n" >> $TMPFILE
26: echo -e -n "Content-Transfer-Encoding: binary\r\n" >> $TMPFILE
27: echo -e -n "\r\n" >> $TMPFILE
28: cat $2 >> $TMPFILE
29: echo -e -n "\r\n" >> $TMPFILE
30:
31: echo -e -n "--$BOUNDARY--\r\n" >> $TMPFILE
32:
33: wget --no-check-certificate --header="Content-Type: multipart/form-data; boundary=$BOUNDARY" --post-file=$TMPFILE \
34: https://{your-domain}/h2/STRLibraryManipurator.do
35:
36: rm -f $TMPFILE
変更が必要な箇所
- 19行目：WebAPIキーを、発行したキーに変更してください。
- 34行目：呼び出し先 URL の
{your-domain}を利用環境に合わせて変更してください。{}は不要です。
JavaによるAPI呼び出し例
Java の HttpClient パッケージを利用し、書庫に文書を登録する API を呼び出す例です。
以下のクラスをコンパイルし、第1引数に書庫文書タイトル、第2引数にアップロードするファイル名を指定して起動すると、書庫に文書が登録されます。
Javaコード
01: package com.dreamarts.sample;
02:
03: import java.io.File;
04: import java.io.IOException;
05: import java.util.ArrayList;
06: import java.util.List;
07:
08: import org.apache.commons.httpclient.HttpClient;
09: import org.apache.commons.httpclient.HttpException;
10: import org.apache.commons.httpclient.methods.PostMethod;
11: import org.apache.commons.httpclient.methods.multipart.FilePart;
12: import org.apache.commons.httpclient.methods.multipart.MultipartRequestEntity;
13: import org.apache.commons.httpclient.methods.multipart.Part;
14: import org.apache.commons.httpclient.methods.multipart.StringPart;
15:
16: public class LibraryManipuratorClient {
17:
18: private static final String CHARSET = "UTF-8";
19:
20: private void process(String title, String filePath) throws HttpException, IOException {
21: List<Part> parts = new ArrayList<Part>();
22:
23: parts.add(new StringPart("func", "create", CHARSET));
24: parts.add(new StringPart("key", "Y70L-T6TJ-E2O8-XHLZ-BPQ9-8VG3-7XVU-O1D8", CHARSET));
25: parts.add(new StringPart("title", title, CHARSET));
26:
27: File upFile = new File(filePath);
28: parts.add(new FilePart("file", upFile, "application/octet-stream", CHARSET));
29:
30: PostMethod post =
31: new PostMethod("https://{your-domain}/h2/STRLibraryManipurator.do");
32:
33: post.setRequestEntity(new MultipartRequestEntity(
34: parts.toArray(new Part[parts.size()]), post.getParams()));
35:
36: post.setContentChunked(true);
37:
38: HttpClient httpClient = new HttpClient();
39:
40: httpClient.executeMethod(post);
41:
42: System.out.println(post.getResponseBodyAsString());
43: }
44:
45: public static void main(String[] args) {
46: LibraryManipuratorClient client = new LibraryManipuratorClient();
47: try {
48: client.process(args[0], args[1]);
49: } catch (Exception e) {
50: e.printStackTrace(System.err);
51: }
52: }
53: }
変更が必要な箇所
- 24行目：WebAPIキーを、発行したキーに変更してください。
- 31行目：呼び出し先 URL の
{your-domain}を利用環境に合わせて変更してください。{}は不要です。