API の呼び出し
オペレーションをリクエストする際には、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://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://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://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://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);
}
}
同時接続数の制限
テナントごとに最大 5 件まで並列して 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 | Standard, Advanced, Lite, Basic, Premium | 1 API 当たり 200 request/min |
Contact | Standard, Advanced, Lite, Basic, Premium | 1 API 当たり 120 request/min |
Organization | Standard, Advanced, 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 | 基準時間の更新までの残り時間 | 秒 |