現在の位置
FrontPage > 開発ガイド
SOBA Web API 開発ガイド
この文書はSOBA Web APIを利用する人が最初に読むものと意図したものです。SOBA Web API を使うと、SOBA mieruka で実現されている機能を各種 Webサイトと連携させることができます。
- SOBA mierukaとは何かを知りたい方はSOBA mierukaのウェブサイトをご参照ください
- APIの詳細について知りたい方はSOBA Web APIリファレンスをご覧ください
- Webアプリケーションの登録はアプリケーション登録ページへどうぞ
開発開始までの手順 †
SOBA Web APIを利用したアプリケーションの開発には
- SOBA mierukaのアカウント
- APIキー
- 秘密鍵
が必要です。すでにSOBA mierukaのアカウントをお持ちの方はそれを利用することができます。 SOBA mierukaのアカウントをお持ちでない場合はSOBA Web APIトライアル利用申込フォームから開発用のアカウントを入手できます。 開発用のアカウントにはいくつか制約があります。 制約なしの正式アカウントの発行は有料サービスとなっております。
APIキーと秘密鍵はSOBA Web APIアプリケーション登録ページで発行しています。 SOBAのアカウントとAPIキーと秘密鍵が揃えば開発を開始できます。 開発ではクライアントライブラリを利用するのが便利です。
SOBA Web APIを使用したシステム開発 †
SOBA mierukaの仕組みとSOBA Web API †
SOBA Web APIはSOBA mieruka クライアントアプリケーションを利用したビジュアルコミュニケーション・システムを構築するための手段です。その使い方を知るにはまずSOBAプロジェクトが提供するサービスであるSOBA mierukaの仕組みを知っておくのがよいでしょう。
下図にSOBA mierukaサービスの仕組みの概略を示します。SOBA mierukaのユーザはまずウェブブラウザでSOBA mierukaのウェブサイトを開きログインします。ログイン後のページでユーザは自分でセッションを開始したり、他の人が立ち上げたセッションに参加することができます。
セッションの開始や参加をしようとするたびに、ユーザはSOBA mierukaのウェブサーバからコマンドファイルをダウンロードします。コマンドファイルはcommand.mkdという名前のファイルで、この拡張子のファイルはSOBA mierukaのクライアントアプリケーションと関連付けられています。それで、コマンドファイルがダウンロードされるとSOBA mierukaクライアントがそれを読み取って、セッションを開始したり参加したりします。作成したセッションの情報はSOBA mierukaクライアントからSOBAプロジェクトが運用しているディレクトリサーバに送信されます。
SOBA Web APIを利用したWebサイト/Webアプリケーションと、ユーザのWebブラウザやSOBAクライアント、およびSOBAのサーバ群との関係は下図のようになります。 SOBA Web APIが提供するのは赤い矢印で示した2と3の部分のやりとりです。 例えばセッション参加のリクエストをSOBA Web APIサーバに送信すると、指定したセッションに参加するためのコマンドファイルのURLが返されます。 ユーザのブラウザに対してそのURLへのリダイレクトを指示すればセッションに参加するためのコマンドファイルがユーザのコンピュータにダウンロードされ、SOBAクライアントがそれを読み取ってセッションに参加します。 最後に、SOBAクライアントがセッションを開始したり参加したりするとそれらの情報はSOBAのディレクトリサーバに送信されます。
SOBA Web APIが提供するもの †
SOBA Web APIを利用して取得できる情報は次の5種類です:
- 認証トークン
- コマンドファイルのURL
- セッション情報
- ユーザ情報
- セッションURL
認証トークンを取得するにはSOBAのアカウントとパスワードが必要です。 コマンドファイルはSOBAクライアントにセッションを開始させたりセッションに参加させたりするのに使われるものです。 コマンドファイルには次の3種類のものがあります:
- セッション開始
- セッション参加
- ログアウト
セッション情報は、認証トークンが表すユーザが参加できるセッションの情報です。 ユーザ情報は、認証トークンが表すユーザと同じグループに所属するユーザの情報です。
セッションURLというのはセッションに参加するためのURLです。 WebブラウザでそのURLにアクセスするとユーザ認証ページが表示され、そこで認証に成功するとSOBAクライアントが起動して、まだ誰もそのセッションに参加していない場合はセッションを開始し、すでに他の誰かがそのセッションを開始している場合にはそのセッションに参加します。
アプリケーションの登録 †
SOBA Web APIを利用するにはAPIを利用するWebアプリケーションを登録する必要があります。 登録用のページでWebアプリケーションのドメインとSOBAアカウント、SOBAのパスワードを入力して送信するとAPIキーと秘密鍵が発行されます。 APIキーと秘密鍵はAPIの使用時に必要となるものです。
入力例 †
利用ドメイン | www.your-application.com |
SOBAアカウント | taro@group1 |
SOBAパスワード | ********** |
「利用ドメイン」にはSOBA Web APIを利用して開発したWebアプリケーションを公開する際に使用するドメインを入力してください。 特に決まっていない場合は何でもかまいませんが、将来的にはここに入力したドメインからのリクエストしか受け付けないようにする可能性があります。 そのときは改めて登録しなおしていただければご利用いただけます。
注意点 †
- 登録の際のSOBAアカウントとパスワードは有効なSOBAアカウントであればどれでも構いません。
APIの概略 †
API一覧 †
SOBA Web APIが提供する機能は以下のものです。より詳しい内容はSOBA Web APIリファレンスを参照してください。
ユーザ認証、ログイン | ユーザの認証トークンを取得する。認証トークンを取得する方法はSOBAが提供する認証ページを利用する方法と、プログラムから実行する方法の2種類があります。以下のAPI呼び出しにはすべて認証トークンが必要となります。 |
ログアウトコマンドURLの取得 | SOBA mierukaクライアントにログアウト処理を実行させます。ログアウトをするとユーザ認証時に発行したトークンが無効化され、SOBA mierukaクライアントは終了します。 |
セッション一覧の取得 | ユーザが参加できるセッション情報の一覧を取得します。 |
ユーザ一覧の取得 | ユーザと同じグループのユーザの一覧を取得します。 |
セッション参加コマンドURLの取得 | セッションに参加するためのコマンドファイルのURLを取得します。 |
セッション作成コマンドURLの取得 | セッションを作成するためのコマンドファイルのURLを取得します。 |
セッションURLの発行 | セッションに参加するための配布可能なURLを取得します。このURLはコマンドファイルのURLではなくWebページへのURLです。ブラウザでこのURLを訪れるとユーザ認証のページが表示されます。 |
クライアントライブラリ †
SOBA Web APIを手軽に利用できるように一部のプログラミング言語についてはクライアントライブラリを提供しています。 ご使用方法は、各ライブラリに添付された文書をお読みください。 現在ライブラリを提供している言語は下記の通りです。