ユーザーAPI
掲載内容以上のサポートはできません。
ご利用にあたっては十分なご理解の上での活用ください。
SuperSaaSは開発中を含むwebhookとAPIを提供するもので、それを利用するサービス、アプリケーションに責任を持つことはできません。
ユーザーAPIを用いてユーザ情報にアクセスすることが可能です。
独自のログインシステムがある場合は、その情報を基にAPIを介してSuperSaaSにアクセスし、ユーザー登録やログインなどをシームレスに連動するメソッドも提供しています。
APIはJSONもしくはXML形式でURIパラメーターを受け取り、結果をレスポンスします。
APIを用いることで、SuperSaaSにユーザー情報を登録や更新することが可能です。
独自システムでもユーザー情報を管理している場合、その情報をアクセス時にAPIに送ることで最新の状態としてユーザー情報を同期することができます。
- API実行用のクリックターゲットとしてボタン要素 作成します。
- クリックされるとAPI認証(チャックサム)を行い、ユーザー情報をAPIに送信します。
- SuperSaaSの既存ユーザーの場合はユーザー情報を更新し、既存ユーザーでない場合は新規ユーザーとして登録します。
- ログイン処理を行い、スケジュールカレンダーを表示します。
ボタンをクリックするたびに情報を更新するため、独自システムで管理しているユーザー情報とSuperSaaSのユーザー情報が同期します。
ただし、あくまでボタンがクリックされることをトリガーとするため、直接のアクセスとなるブックマークやブラウザの戻る機能などAPIがコールされない場合があることに注意が必要です。
この点が問題である場合、独自システムによるユーザー情報の更新をトリガーにとする、別途のユーザー情報更新のためのAPIをコールするシステムを構築ください。
また、不測の利用の可能性がある不特定多数ではなく、独自システムで管理している既存ユーザーに対してのみ開示する仕組みであることが望ましいかもしれません。
あるいはもっとシンプルに、APIによるユーザー情報の同期は独自システムの管理機能として別途のAPIコールとし、ユーザーにはスケジュールへのログイン、リダイレクト機能の開示のみとしてAPIを活用する方法が安全であるかもしれません。
APIを用いてSuperSaaSのユーザー情報を取得して、独自システムに反映する手段も構築可能ですが、およそ煩雑になるためどちらかを主とする運用が推奨されます。
以下は、SuperSaaS側でのユーザーによるログインやユーザー情報管理に制御をかけて、独自システム側からのコントロールとなる設定例です。
-
SuperSaaSへのログインを独自に制御するため、管理画面のアクセスコントロールにある誰がログイン名を作成出来ますか?で を選択し、ユーザーによるログイン画面の利用を制限します。
-
ログイン画面を利用しないので、ログイン名は必要ありません。ユーザーログイン名を作成する時どんな情報を入力しますか?の はチェックを入れておくべきでしょう。
-
同じく、パスワード項目も必要ありません。
-
ユーザー自身によるSuperSaaSでのユーザー情報の編集を抑制するため、追加のセキュリティ対策が必要ですか?で にチェックを入れます。
-
スケジュールURLなどにダイレクトなアクセスがあるかもしれませんので、管理画面のレイアウト設定にある あなたのURLにデフォルトとなるURLを設定します。
ログイン無しのアクセスがリダイレクトされます。
APIを用いたログイン
APIを用いたユーザーAPIの利用は、登録もしくは更新となるため、基本的にはユーザー情報の全てをパラメーター含めます。
<form method="post" action="https://www.supersaas.com/api/users"> <input type="hidden" name="account" value="Your_account_name"/> <input type="hidden" name="id" value="1234fk"/> <!-- A unique key to identify the user. See below --> <input type="hidden" name="user[name]" value="joe@client.com"/> <!-- Any string. Needs to be unique --> <input type="hidden" name="user[phone]" value="123-456-789"/> <!-- values for other fields, see the bottom of the page for a list --> <!-- you can add and remove fields in the "Access Control" screen --> ... <input type="hidden" name="checksum" value="A4E67...DFEF"/> <!-- 32 digit MD5 Hash, see below --> <input type="hidden" name="after" value="schedule_name"/> <!-- where you send your user after sign on --> <input type="submit" value="Book now"/> </form>
上記スニペットに関してはこちらをあなたのアカウントで参照ください。
コンテンツ管理システムとしてJoomla、Drupal、WordPressを使用している場合は、各モジュールのプラグインをダウンロードできます。
・ Joomla module
・ Drupal module
・ WordPress plugin
データベースキー
各トランザクションごとに、認証とユーザーレコードの特定として一意なデータベースキーを持ちます。
キーとする内容は以下の3つが可能です。
- 32ビット ユニークキー:
独自システムで用いられているデータベースのユニークなインデックス番号に適しています。
キーは下のSuperSaaSユーザーIDと区別するため、文字列「fk」(foreign key)を付けてポストフィックスします。 - SuperSaaSユーザーID:
SuperSaaSのユーザーIDは全て数字の32ビットユニークキーです。
ユーザーレコードの新規登録時に、そのSuperSaaSユーザーIDを記録して、以後の更新セッションでキーとして用います。 - 文字列(50バイト):
数字で始まらない文字列を使用します。
数字で管理していない場合などに用いることができます。
任意の文字列が使用できますが、ユニークであることが必須です。
ユーザーレコードと一意である管理が必要なため、意味を持つ文字列の場合は、重複や安易な変更が行われない文字列でキーとしてください。
氏名などはそのままでは一意になりにくく、また不意の変更も考えられます。
API認証
認証についてはこちらを参照下さい。
備考
認証で管理者権限となり、ユーザーはログインフォームでユーザーパスワードを入力する必要はありません。
ユーザーパスワードを用いることも可能ですが、不測の露出やMD5ハッシュ解析などを避けるためにも推奨しません。
レコードが正常に作成もしくは更新された場合、ユーザーはafter要素に含まれるURLへリダイレクトされます。
指定するURLにSuperSaaSの表示用URIパラメーターを用いることで、指定のスケジュール表示へ遷移することも可能です。
単純にログインを促すボタンやリンクを提供するだけでは、ユーザー情報の同期として不安定です。
必ずしも提供されたボタンやリンクを景趣してアクセスされるとは限りません。
また、独自構築されたユーザー情報が更新されても、提供されたボタンやリンクを介するまでSuperSaaSに反映することもありません。
密に同期を望む場合は、独自システム上でも更新毎にSuperSaaSへ反映する仕組みを構築する必要があります。
単純ログイン (プログラム構築なし)
リンク先URLにパラメータを付与されたGETを用いたAPIアクセス、もしくはPOSTでパラメータを内包してAPIアクセスできます。
https://www.supersaas.com/api/login?account=Your_acount_name&after=Schedule_url&user[name]=user@client.com&checksum=A4E67...DFEF
→ ログインする
リクエストのヘッダーにOrigin要素が含まれている場合、サーバーは適切なCORSヘッダーを追加します。
この場合、ブラウザ内のAJAX呼び出しから要求が送信されます。
SSL暗号化(https)接続を介してブラウザからリクエストを送信することを強く推奨します。
ユーザーAPI
ユーザーAPIはRESTfulです。
Ruby on Railsのアクティブリソースのように、適切に書き込まれたライブラリとなっています。
各コールには、URIパラメーターとしてアカウントとパスワードを追加するか、基本認識ヘッダー(GET、POST、PUT、DELETEなど)を利用して認証します。
たとえば、https://supersaas.com/api/users?account=YourName&api_key=secret
のようにコールします。
また前述の通り、MD5ハッシュを用いたチェックサムを利用する事もできます。
さらにセキュリティーのために、SSLを介したアクセスによるコールも可能です。
新規ユーザーの作成
/api/users.jsonに、JSON形式のユーザー情報をURIパラメーターしてHTTP POSTすることで新しいユーザーを作成することができます。
パラメーターとするフィールド情報は必ずURLエンコードするようにご注意ください。
フィールド情報の概要は後述を参照ください。
POST /api/users
(SuperSaaS will assign a key)POST /api/users/{id}
(You provide your own key in the format 9999fk
)
成功した場合、ステータスコード201(Created)がレスポンスされます。
レスポンスヘッダのLocation
要素に、後でユーザーを取得するために使用できるURLが含まれています。
例:Location: https://www.supersaas.com/api/users/1234.xml
作成したオブジェクトのSuperSaaSユーザーID(上の例の場合ID:1234)は、このURL情報から取得することができます。
メールアドレスが無効など、バリデーションエラーが発生した場合、ステータスコード422 (Unprocessable Entity)となりエラーメッセージがレスポンスされます。
ユーザー情報のキーが既存である場合、APIコールは登録ではなく既存情報の更新となります。
duplicate=raiseをURIパラメーターに追加することで、既存の更新を行いません。
ただし、この場合もステータスコード422 (Unprocessable Entity)がレスポンスされます点にご注意ください。
ユーザー情報のキーにピリオドなど機能的な文字列が含まれる場合、正常な動作が行われません。
機能的な意味で危険な文字列を含む場合、{}で囲むことで、単なる文字列として扱うことも可能です。
例:/api/users?id={id}
データのフォーマット
ユーザー情報を構成するフィールドは、管理画面のアクセスコントロールで設定されます。
ログイン名は必須のフィールドとなります。
それ以外のフィールドは選択可能で、登録時に内容が指定されていない場合、デフォルトの値(通常はブランク)が設定されます。
フィールド | 概要 | |
---|---|---|
name | 必須 | ログイン名です。最大50バイトの制限があります。 e-mailをログイン名としている場合はメールアドレスとなります。 |
email | 選択可 | e-maiアドレスです。e-mailをログイン名としている場合は使用されません。 |
password | 選択可 | ユーザーのログインパスワードです。 |
full_name | 選択可 | 氏名、住所、携帯電話、電話番号です。 それぞれUTF-8の文字列として格納できます。 |
country | 選択可 | 2文字のISO 3166-1の国名コードとして格納できます。 |
field_1 | 選択可 | 2つのカスタムフィールドおよびスーパーバイザフィールドの内容です。フィールド名ではありません。 |
credit | 選択可 | 保有ポイント・クレジットの値が格納されます。 |
role | 選択可 | 権限情報が格納されます。3 : ユーザー (default)4 : Superuser-1 : Blocked user |
webhook | 選択可 | webhook=trueが設定されている場合、アカウントに接続されているウェブフックトリガーとなります。 |
レスポンスされたXMLには、上記のものに加え次のフィールドが含まれます。
フィールド | 概要 |
---|---|
id | ユーザー登録時に付与される一意なSuperSaaSユーザーIDです。 |
fk | 32ビット ユニークキーを指定した場合にユーザに割り当てたキー(foreign key)です。 |
created-on | ユーザーが登録された時間(UTC)です。 |
使用例
独自システムのユーザー情報の管理番号から、ユーザーIDを32ビット ユニークキーで登録したものとして、「fk」を付与した管理番号
567
を指定してコールしています。
POST /api/users/567fk.xml
<?xml version="1.0"?> <user> <full-name>Full Name</full-name> <name>user@example.com</name> </user>
{ "full_name": "Full Name", "name": "user@example.com" }
成功するとステータスコード201 (Created)
が返ります。レスポンスに内容はありません。
もしパラメーターを用いる場合、フィールド名のダッシュをアンダースコアとし、値となる情報は必ずURLエンコードしてください。
例:user[field_name]
POST /api/users/567fk.json?account=demo&password=secret&user[name]=user@example.com&user[password]=secret&user[full_name]=Full%20Name
上記の例では、認証としてMD5ハッシュのチェックサムを用いています。
パスワードの直接表記はセキュリティ的に問題があるため、MD5ハッシュを用いた暗号化を強く推奨します。
ユーザーを指定して情報の取得
GET /api/users/{id}.json
それ以外である場合は登録時に用いられたユーザーIDとして処理が行われます。
もしユーザーIDがアルファベットの文字列の場合、ネームフィールドに保存されます。
文字列である場合はURLエンコードされます。
該当ユーザーがある場合、ステータスコード
200 (OK)
が返り、ユーザー情報がレスポンスされます。該当ユーザーが見つからない場合は、ステータスコード
404 (Not Found)
が返ります。<user> ... </user>
{ "id": "123456", "name": "example", "email": "example@gmail.com", ... }
全てのユーザー情報を取得
GET /api/users.json
200 (OK)
が返り、ユーザー情報がレスポンスされます。ユーザー情報の取得は、100件を通常の最大取得数としています。
/api/users?limit=500
のようにlimit
パラメーターで最大数を指定することができます。1000件を超えるなど長大な場合など、
/api/users.json?limit=1000&offset=1000
として、offset
パラメーターを活用した分割取得も可能です。<users> <user> ... </user> <user> ... </user> </users>
[ { "id": "123456", "name": "example", "email": "example@gmail.com", ... }, { "id": "789123", "name": "example2", "email": "example2@gmail.com", ... } ]
ユーザー情報に紐づくフォーム情報
フォームがユーザーに関連付けられている場合は、パラメーターに form = true
を追加してフォームのデータを取得できます。
フォームAPIも合わせて参照ください。
ユーザー情報の更新
ユーザー情報の更新はHTTP PUTリクエストで/api/users
APIをコールします。
ユーザーの作成と同様に、XML、JSON形式でURLエンコードされたURIパラメーターを使用します。
PUT /api/users/{id}.json
指定されたユーザーIDで特定されるユーザー情報が更新されます。
成功した場合、ステータスコード200 (OK)
が返ります。
失敗した場合は、ステータスコード422 (Unprocessable Entity)
が返り、エラーがレスポンスされます。
もし、該当するユーザー情報が見つからない場合、APIは新規登録を試みます。
自動的に新しいレコードを作成しないためには、パラメーターにnotfound=error
もしくはnotfound=ignore
を追加します。
それぞれ、ステータスコード404 (Not Found)
、200 (OK)
が返ります。
ユーザーIDにSuperSaaSユーザーIDを用いられている場合、該当ユーザーが見つからない時には常にステータスコード404 (Not Found)
が返ります。
ユーザー情報の削除
ユーザー情報の削除はHTTP DELETEリクエストで/api/users
APIをコールします。
DELETE /api/users/{id}
指定されたユーザーIDに該当するユーザー情報を削除します。
成功した場合、ステータスコード200 (OK)
が返ります。
該当ユーザーが存在しないなど、失敗した場合はステータスコード404 (Not Found)
が返り、エラーがレスポンスされます。
_method=DELETE
をパラメーターに追加することで、POSTリクエストでも代行することが可能です。
トラブルシューティング
- もしメールアドレスが不正などメールアドレスバリデーションエラーの場合、アカウントの設定を確認ください。
-
もしユーザーのリダイレクトに成功してもログインができない場合、クッキー情報が失われている可能性があります。
これはAPIにアクセスする際に使用しているドメインとユーザーを送信するスケジュールのドメインが異なる場合に発生します。
ドメインはどちらも同じである必要があります。 -
ログインせずにスケジュールにアクセスできる場合、不特定多数への開示は推奨されません。
万が一、不正な利用が発生しても、そのクライアントを特定できない可能性がありますので、必ず特定できるユーザーのみ利用できる仕組みとすることを推奨します。
特定できないユーザーには、通常の使い方でのアクセスか、あるいは、別の同等スケジュールの開示で代替願います。 -
もしBad request – unknown attribute: field-1のようにリクエストエラーの場合、パラメーター名に注目ください。
XMLの場合、パラメーター名のハイフンをアンダースコアにします。
コール方法でuser[field_1]
や<field-1>
となります。