アラームボックスAPI Getting Start

アラームボックスAPIのご利用を検討してくださり、ありがとうございます。
本ページではアラームボックスAPIの概要と利用手順を説明します。

アラームボックスAPI概要

アラームボックスAPIはアラームボックスのモニタリングサービスに関するAPIを提供します。
APIを活用することで、お客様のシステムや利用しているサービスでアラームボックスをご利用いただくことが可能になります。
main

現在アラームボックスAPIで提供している機能は以下のとおりです。

<機能一覧>

  • 取引先の一覧取得
  • 取引先の登録
  • 取引先の削除
  • 取引先の情報取得
  • アラーム情報の取得

※ パワーサーチサービスのAPI提供は対象外となりますのでご注意ください。
※ アラームボックスAPIのご利用にはアラームボックスのモニタリングサービスの利用登録が必要です。

APIエンドポイント

https://api.alarmbox.jp
(httpsのみ)

認証

OAuth 2.0を使用します。 アプリケーション利用者はアラームボックスのIDとパスワードをアプリケーションに教えることなくアラームボックスの連携を認証でき、連携したアプリケーションでは付与した権限に応じてアラームボックスAPIを経由して情報の取得や登録などができるようになります。

アラームボックスAPIでは下記２つのフローをサポートしています。

  • Authorization Code Flow (Webアプリ向け)
  • Implicit Flow (Mobileアプリ向け)

データフォーマット

リクエスト、レスポンスともにJSON形式をサポートしています。
詳細はAPIリファレンスを確認してください。

利用手順(開発者向け)

エンドユーザーのアプリ利用手順

エンドユーザーとは上記手順で作成したアプリケーションを経由してアラームボックスを利用(連携)するユーザーを指します。
エンドユーザーの連携設定は基本的にはアラームボックスへログインし「承認」をクリックするだけで完了します。

一般的な流れは以下のようになります。

  1. 連携元アプリケーションにて実装される連携ボタンをクリックする
  2. 下記のような画面が表示される
  3. ユーザーが「承認」する
  4. アプリケーションに設定されているリダイレクトURIに遷移
    →元のアプリケーションに戻る

アプリケーションの登録

アラームボックスAPIを利用するアプリケーションを登録します。登録によりアプリケーションのIDとSecretが発行され、アラームボックスユーザーが当該アプリを利用できる状態となります。

  • 開発者のアカウントでアラームボックスAPI管理にログインします。

    • ユーザーID、パスワードはアラームボックスサービスにログインするものと同じです。

  • アプリケーション一覧にアクセスします。

  • 「+新しいアプリケーションを登録」をクリックします。

  • アプリケーション名、コールバックURIを入力し保存します。

    • ※ ローカル環境用のアプリケーションでは、コールバックURIに「urn:ietf:wg:oauth:2.0:oob」をご利用ください。

  • アプリケーションが登録され、IDとSecretが表示されます。

  • アプリケーションの一覧にアプリケーションが追加されます。

  • アプリケーション名をクリックすると登録したアプリケーション名をクリックすると、この画面を確認できます。

アクセストークンの取得

  • アクセストークンを取得するには、認証用URLにて認可コード（Authorization code）を取得し、それを用いてhttpリクエストを送る必要があります。

認可コードの取得

パラメータにアプリケーション登録で生成された情報を指定して認証用URLにリクエストを送信してください。
リクエストが成功すると、リダイレクトのパラメータにcodeが付加されますので格納してください。
※リダイレクトURIにurn:ietf:wg:oauth:2.0:oobを指定している場合はアプリケーション画面のWebアプリ認証用URLにアクセスして取得することも可能です。

  • 認証用URL
    https://api.alarmbox.jp/oauth/authorize(GET)
  • パラメータ一覧 (全て必須)
    項目名 説明
    client_id アプリケーションID
    redirect_uri アプリケーションに登録したコールバックURL
    response_type "code"(固定)
    scope read , customer:create , customer:delete
  • リクエストサンプル 
    https://api.alarmbox.jp/oauth/authorize?
    client_id=xiBZpDIlKt1q0koE8uNLqmxfeUhLAxJ6n3oqdGMlo4w&
    redirect_uri=urn:ietf:wg:oauth:2.0:oob&
    response_type=code&
    scope=read+customer:delete+customer:create
  • リダイレクトURL 
    https://hoge.example.com/callback?code=jflkajklfjlahroihalrhalkhrklahra

アクセストークンを取得します。

前項で取得した認可コードを使用して、アクセストークンを取得します。
下記パラメータを指定してトークン取得用URLにリクエストをPOST送信してください。

  • トークン取得用URL
    https://api.alarmbox.jp/oauth/authorize(POST)

  • パラメータ一覧 (全て必須)

    パラメータキー 設定値
    grant_type "authorization_code"(固定)
    client_id アプリケーションID
    client_secret シークレットキー
    code 認証コード
    redirect_uri 遷移先のURL

  • curlコマンドを使ってアクセストークンを取得する場合のサンプル

    curl -i -X POST -d grant_type=authorization_code \
-d client_id=xiBZpDIlKt1q0koE8uNLqmxfeUhLAxJ6n3oqdGMlo4w \
-d client_secret=q_Qr14VQml1b4vPw7dWeDK_tsotcUGV7Ri5i7TLFBUE \
-d code=CU8wbymHIiKUYy6tsY8dbCbzsZNdEucx70d2ZpBLz3Q \
-d redirect_uri=urn:ietf:wg:oauth:2.0:oob \
https://api.alarmbox.jp/oauth/token

  • レスポンス

    パラメータキー 設定値
    access_token アクセス トークン
    refresh_token リフレッシュ トークン
    token_type Bearer（固定）
    expires_in 有効期間
    scope 許可された権限
    redirect_uri 遷移先のURL
    created_at トークンを生成したタイムスタンプ

  • 例

    {
"access_token": "l-TGspUX-fPghhcKpxWfkyQXbTQnvSejqeTVXlKiKo8",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "JlV8SeYcWwGrsAMh8ylftHQGttitwd2NRibImg3QUes",
"scope": "read customer:delete customer:create",
"created_at": 1618206635
}

アラームボックスAPIをコールする

リクエストヘッダにアクセストークンを指定してください。

Authorization: Bearer {ACCESS TOKEN}
  • サンプル
    • /common/v1/users/meをコールする
    curl -H "Authorization: Bearer 123456abc" https://api.alarmbox.jp/common/v1/users/me
    • 下記のようなJSONが返ってきたら成功です。
    user":{"id":XXXX,"member_id":XXX,"email":"[your_email_address]"}}

APIリファレンスの利用

アラームボックスAPIリファレンスを下記サイトで提供しております。
https://alarmbox.github.io/alarmbox_api_docs/refs/
認証情報を入力することでAPIの挙動を確認すことができますのでご利用ください。
また同サイトからopenapi形式(yaml)をファイルでダウンロードできますのでご活用ください。

＜利用手順＞

  1. 認証設定をします
    • 鍵マークをクリックします
    • 認証設定画面が表示されたらアクセストークンを入力します。
    • 「Authorize」で問題なければ下記の画面が表示されます。
      「Close」で閉じてください。
    • 鍵マークが施錠した状態になっていることを確認します。
  2. APIのコール
    • 利用したいAPIのリファレンスを開きます
    • 「Try It Out」をクリックします。
    • 必要なパラメータを入力し、「Execute」をクリックします。
      • 問題なければURLや実際のレスポンスなどが表示されます。

※ 画面操作等はswagger-uiのリファレンスや情報をご参照ください。