API の呼び出し

環境

LINE WORKS では、下記のようにテストとサービスの 2 つの環境を提供しています。

サービス環境: https://apis.worksmobile.com
テスト環境: https://sandbox-apis.worksmobile.com

オペレーションをリクエストする際には、HTTP メソッドとリクエスト URL を結合します。下記は、サービス環境でメールを送るオペレーションの例です。

例) メール送信オペレーション

POST https://apis.worksmobile.com/{API ID}/mail/sendMail

各 API の説明にて、サービス環境用のリクエスト URL を確認できます。

Request共通

API を呼び出す際には、必ずヘッダーに認証トークンとコンシューマーキーを含める必要があります。トークンとコンシューマーキーの発行については、API認証の準備を参照してください。

ヘッダーにトークンとコンシューマーキーを設定する方法は、下記の通りです。

注意

Authorization タイプに'Bearer'を明示しなければなりません。'Bearer'と'Token'の間には空白(space)を必ず入れるようにしてください。

method.setRequestHeader("consumerKey", "コンシューマーキー");
method.setRequestHeader("Authorization", "Bearer トークン");

Response 共通

API の呼び出しに失敗した場合、エラーコードとエラーメッセージが返されます。

参考

API の呼び出しに成功した場合、結果のフォーマットは API ごとに異なりますので、各 API の説明を参照してください。

プロパティ	タイプ	必須	説明
errorCode	String	Y	エラーコード
errorMessage	String	Y	エラーメッセージ

詳細なエラーコードとエラーメッセージの種類は、下記のとおりです。

コード	REST API RESPONSE コード	メッセージ	説明
001	404	Not support url	非対応 URL
002	404	Not support port	非対応 Port
024	401	Authentication failed	コンシューマーキーとトークンの認証失敗
028	401	Authentication header not exists	コンシューマーキーとトークンがヘッダーに含まれていない
029	401	Malformed authentication header	ヘッダーのコンシューマーキーとトークン形式が異なる
041	403	Not allowed tenantApiId	許可されていない API ID
042	403	Not allowed consumerKey	許可されていないコンシューマーキー
043	403	Not allowed remote ip	許可されていない IP
044	403	Not allowed domainId	許可されていないドメイン
045	403	Not allowed service	権限のないサービス
051	404	Api not exists	存在しない API
064	405	Malformed http method	非対応 HTTP メソッド
065	400	Mandatory parameter not exists	必須パラメータの不足
081	400	Target not exists	対象が存在しない
083	500	Additional information fail	追加情報の獲得に失敗
085	429	Daily quota fail	一日あたりのクォータ(最大回数の制限)超過
086	503	Service use fail	サービス(メール、トーク Botなど)が利用できない
087	403	Domain stop	ドメインが一時停止されている
088	403	Blacklist	ブラックリストに含まれている
089	400	Malformed json parameter	不正な JSON パラメータ
090	503	Service fail	サービス(メール、トーク Bot など)内部エラー例) {errorMessage=Service fail, HTTP/1.1 400 bad_path(name), errorCode=090}
092	429	API rate limit exceeded	Rate Limit 超過
999	500	Unknown error	不明なエラー

API ごとに発生するエラーコードとエラーメッセージについては、各 API の説明を参照してください。

サンプルコード

ここでは、LINE WORKS Bot Platform API の種類別サンプルコードを提供します。

サービス API サンプルコード

ソースコードに必要な consumerKey は、LINE WORKS Developer Consoleで発行できます。


/* authorization codeリクエスト */

var consumerKey = "LQwDde6x8eV4ROOCOdSW";
var url = "https://sandbox-auth.worksmobile.com/oauth/authorize?client_id=" + consumerKey
               + "&redirect_uri=https://mydomain.com/getToken"
               + "&domain=mydomain.com";

window.open(url, 'authorize' , 'width=600px,height=800px');


/**
 * https://mydomain.com/getToken
 * Authorization Code 獲得後に Access Token をリクエスト
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServiceApiTest {

    public void testGetAccessToken() throws Exception {
        String url = "https://sandbox-auth.worksmobile.com/oauth/token";
        String consumerKey = "LQwDde6x8eV4ROOCOdSW";
        String authorizationCode = "QkJxMFc4ekRnMGdLNjhOMQ==";
        String domain = "mydomain.com";

        PostMethod method = new PostMethod(url);
        NameValuePair[] parameters = new NameValuePair[3];
        parameters[0] = new NameValuePair("client_id", consumerKey);
        parameters[1] = new NameValuePair("code", authorizationCode);
        parameters[2] = new NameValuePair("domain ", domain);
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
        /* response={"errorCode":"00","expire_in":"604800","refresh_token":"AAAAT/bdZsj81ULzym+URwKwM+OEj69MPhkqDuFiWMRjSZkR+Yk","access_token":"AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW"}
         response から accessToken を抽出して保存することを推奨します。*/
    }
}


/** 
 * サービス API の呼び出し
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServiceApiTest {

    public void testServiceApi() throws Exception {
        String url = 
             "https://sandbox-apis.worksmobile.com/kr1wwTrYrbIot/calendar/getCalendar";
        String consumerKey = "LQwDde6x8eV4ROOCOdSW";
        String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW";

        PostMethod method = new PostMethod(url);
        method.setRequestHeader("consumerKey", consumerKey);
        method.setRequestHeader("Authorization", "Bearer " + token);

        NameValuePair[] parameters = new NameValuePair[1];
        parameters[0] = new NameValuePair("calendarId", "1234");
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
    }
}

サーバー API サンプルコード

ソースコードに必要な consumerKey と token は、LINE WORKS Developer Console で発行できます。


import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServerApiTest {

    public void testServerApi() throws Exception {
        String url = 
                     "https://sandbox-apis.worksmobile.com/kr1wwTrYrbIot/admin/getDomain";
        String consumerKey = "dz0jtXyXc9Zo953HdjZA";
        String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLWt";

        PostMethod method = new PostMethod(url);
        method.setRequestHeader("consumerKey", consumerKey);
        method.setRequestHeader("Authorization", "Bearer " + token);

        NameValuePair[] parameters = new NameValuePair[1];
        parameters[0] = new NameValuePair("params", "{\"domain\":\"mydomain.com\"}");
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
    }
}

同時接続数の制限

テナントごとに最大５件まで並列して API を呼び出すことができます。許容された同時接続数を超える場合、API の呼び出しに失敗することがあります。

Rate Limit

Rate Limit とは一定時間内に実行可能な API 呼び出し回数です。ユーザーの API 呼び出し数が Rate Limit を超過すると、一時的に呼び出しが制限されてエラーを返します。呼び出し制限時の response は以下の通りです。

コード	REST API RESPONSE コード	メッセージ	説明
092	429	API rate limit exceeded	Rate Limit 超過

現在、Message、Contact、Organization の 3 カテゴリーに Rate Limit が適用されています。制限値は製品プランによって異なります。

適用対象

Category	Product	Rate Limit
Message	Free	1 API 当たり 60 request/min
Message	Lite, Basic, Premium	1 API 当たり 200 request/min
Contact	Lite, Basic, Premium	1 API 当たり 120 request/min
Organization	Lite, Basic, Premium	1 API 当たり 1000 request/min 以下の API は、 1 API 当たり 600 request/min ●メンバー追加 ●メンバー修正 ●メンバー部分修正 ●メンバー削除 ●メンバー削除の取り消し ●メンバー即時削除

参考

Organization APIを使用する場合、注意を確認してください。

Rate Limit が適用されている API については、レスポンスのヘッダーに下記 3 種類のパラメータが追加され、現在の呼び出し回数、残りの呼び出し可能な回数および Rate Limit 更新までの時間を確認できます。

ヘッダー	説明	単位
RateLimit-Limit	基準時間ごとの API 呼び出し回数
RateLimit-Remaining	基準時間ごとの残りの API 呼び出し回数
RateLimit-Reset	基準時間の更新までの残り時間	秒

LINE WORKS Developers