このチュートリアルにはupdatedバージョンがあります。

APIドキュメンテーション

ユーザーデータベース同期とシングルサインオン

このページは上級者の方用です。このページに関するご質問、サポート等はお受けする事が出来ませんので全て自己責任にて行って下さい。もしあなたのサイトがログインシステムとデータベースを持っている場合このAPIでSuperSaaSのデータベースと同期する事が可能です。この事によりあなたのユーザーが登録とログインを一回で行う事が可能です。

APIを使用することでSuper SaaSデータベースを常に最新の状態にしていくために、いくつかのオプションが以下にあります。最も簡単な方法はシングルボタンにあります。:

  1. サイト上に現時点でサイトにログインしている人のすべての関連情報を含む"Book Now"のボタンを作ります。
  2. そのボタンをクリックするとSuperSaaSの APIに情報が表示されるとともに、他者の書き込みを阻止する確認作業が行われます。
  3. 初めてご利用の場合は入力された情報をもとに新しいユーザーアカウントが作成され、SuperSaaSに送信されます。初めてのご利用でない場合は現存する情報が必要に応じて更新されます。
  4. 利用者は次回ご利用の際には自動でログインすることができます。

この作業方法は、初期のフルシンクのせずに、頻繁にSuperSaaSを利用しているあなたのユーザーのサブセットだけにシンクすることができます。理論的には、もしあなたがボタンを実装した場合のみ、データベースがシンク外に飛び出す、小さなリスクがあります。これは、もしユーザーの情報を、あなたのサイト上で変更し、そのままボタンをクリックせずにSuperSaaSに戻った場合に起こります。例えば、それは、そのページにブックマークをつけたからです。もし、これが、あなたがサーバーサイドを実装する問題ならば、APIが下記の詳細を呼び出し、あなたのサーバーから更新された情報を、ユーザー情報があなたのサイト上で変更される毎に、直接SuperSaaSに送ります。 APIコールは、既存しないユーザーに関して、不作動する可能性が多少あります。ですから、SuperSaaSのアクティブユーザーのサブセットのみで維持していただけます。

上記の方法と違う方法としましては、あなたのユーザーデータベースの初期シンクをすることです(手入力、又は、自動的)、あなた自身のデーターベースを更新する毎に、あなたのサーバーからAPIコールに送られ、SuperSaaSをシンク状態に維持します。その後、自動的にそれらをログインできる、単純なリンクを作成して、あなたのスケジュールにリダイレクトできます。

SuperSaaSの変更に伴い、あなた自身のデーターベースを作成することが出来ます。しかし、話し合いの後、あなたはSuperSaaSをリードし、従わせるデーターベースを作成したいと理解しています。 従って、あなたは、人々が、SuperSaaSデータベース内で、彼らの情報を変更することを避けたいのなら、以下の設定を作成してください。:

作成とログイン

シングルサインオンを実装する為の、最も簡単な方法は、あなたのサイトから、ユーザーを送るとき、必要なすべての情報を提供する事です。SuperSaaSが、既存するユーザーかどうかを確認し、必要に応じて、データベースのレコードを更新、作成します。

これを作動する為に、あなたのサイト上に設置する例示HTMLスニペットです。:
<form method="post" action="http://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モジュール、Drupalモジュール、又はWordPressプラグインをダウンロードできます。Joomla module, Drupal module or WordPress plugin.

データベース・キーの3つのオプション

双方のデータベースの変更の記録をつける為に、同じユニーク・キーを使用する必要があります。このIDは、変更が必要なレコードを特定する為の各トランザクションと一緒に送られる必要があります。簡単な実装の手助けの為に、3つの選択肢があります。:

  1. あなただけのユニークな32ビット数を提供します。一般的に、あなた自身のユーザーデータベースのインデックス・キーが適しています。あなたが、あなた自身のキーを示していることを、あなたのIDに”fk”(外部キー)のレターを添えてポストしてください。
  2. 内部SuperSaaSユーザーID(こちらも32ビット数です)を使用することが出来ます。あなたが新しいレコードを作成した時に、そのIDを取り出し、あなた自身のデーターベース内に収納しなくてはなりません。その後、それは、あなたがレコードを更新する時に一緒に送られます。
  3. あなたは、人の名前をキーとして使用できます。数字で始まらない、ユニークな50バイト文字列です。もし、この価値を変えてしまう可能性のある文字をキーとして利用するのは、あまりお勧めできません。それを変えるたびに、ブッキングから切断されてしまうかもしれないからです。もし、あなたのデーターべスキーが、32バイト数以外の何かであるのなら、よく考えてキーを登録してください。

MD5ハッシュ・チェックサムを利用した認証

APIは、いくつかの違うタイプの認証をサポートします。 サーバーからサーバー通信に対しては、URLパラメーターとして、あなたのアカウント名とパスワードを送るか、HTTP基本認識ヘッダー、SSLによって接続を保護する選択もあります。しかしながら、当然のことですが、上記のスニペットのようなHTMLにあなたのアカウントパスワードを入力してはいけません。そのページにアクセスした人に、あなたのパスワードを明かしてしまうことになります。HTMLの認識の為には、パスワードを送らずにリクエストし、いくつかのフィールドのワンウェイMD5ハッシュを計算し、リクエストに追加します。 そのハッシュは、あなたのアカウント名、ユーザー名、あなたのアカウントパスワード(ユーザーパスワードではありません)を含む、連結した文字列から、割り出されます。それは、あなた自身とSuperSaaSしか知らないアカウントパスワードを含んでいるので、他の誰にも割り出すことは出来ません。チェックサムは、訪問者名を含むので、各訪問者によって、違います。ブラウザーによって実行される為に、安全に、それをAJAXコールに入力できます。殆どの言語が、MD5ハッシュを割り出す為の簡単な方法を提供しています。例えば:

PHP: $user = 'user_name@client.com';$checksum = md5("Your_account_nameYour_account_password$user")
Ruby: checksum = Digest::MD5.hexdigest("Your_account_nameYour_account_password#{'user_name@client.com'}")

フォームは、すでに、チェックサムで認証されているので、ユーザーパスワードを提供する必要はありません。ユーザーパスワードを送ることは出来ますが、避けたほうが良いでしょう。何故なら、ウェブページ上で、見られる可能性があります。 もし、レコードが正常に作成、又は更新された場合、ユーザーは、”後(after)”バラメーターを含むURLにリダイレクトされます。あなたは、ユーザーが、あらかじめ決められた日付と表示に行くことを、確実にする為に、このURLに追加項目を提供できます。また統合チュートリアルに説明されているように、予約欄用のあらかじめ入力された項目を含むことも出来ます。統合のチュートリアル.

もし、あなたがサインオンボタンを提供し、そこで終わるのであれば、シンクを抜け出せる二つのデータベースがあります。もしかしたら、受け付けれらない恐れもありますが。 例えば、誰かが、彼の情報を、あなたのサイト上で変え、ひょっとすると、彼は彼のブラウザー歴を利用し、その後、リンクを通らずに、彼はSuperSaaSへ戻るかもしれません。 また、あなたがあなた自身のデータベースから削除したユーザーは、SuperSaaSデータベースから削除することは出来ません。 これを避ける為に、あなたのサーバー上で、ユーザー情報を変更する毎に、APIコールに以下の詳細を送ることによって、あなた自身のサーバーからSuperSaaSデータベースを更新することができます。

ログインのみ(作成無し)

あなたが、手入力、又は下記のAPIコールにて、すでにデータベースをシンクさせられた場合、上記のコールと同じパラメーターを利用し、下記のリンク(POST、又は、GET)にてユーザーをログインできます。:

http://www.supersaas.com/api/login?account=Your_acount_name&after=Schedule_url&user[name]=user@client.com&checksum=A4E67...DFEF

ユーザーの、読み取り、作成、更新、削除

ユーザーデータベースのAPIはRESTfulです。Rails' Active Resource上のRubyのように、適切に書き込まれたライブラリーによって、利用可能です。 各コールには、URLのパラメーターとしてあなたのアカウントとパスワードを追加するか、ベーシックHTTP認証を利用して確認する必要があります。例として: "http://supersaas.com/api/users?account=YourName&password=secret".です。また上記で述べたMD5チェックサムを利用する事もできます。さらにセキュリティーのために、SSLを使うことも出来ます。

新規ユーザーの作成

POST /api/users   (SuperSaaS will assign a key)
POST /api/users/{id}   (You provide your own key in the format 9999fk)
リクエストには、新しいユーザーと示すXMLドキュメント、もしくはエンコードしたURIパラメーターを含めるべきです。フォーマットについてはドキュメントの最後をご覧ください。 レコードが正しく作られていれば、ステータスコード201(”作られた”)のヘッダーのレスポンスがあります。 レスポンスヘッダーのロケーションフィールドは、後で検索に使用できるユーザーや例えばロケーションのURLを含みます。 Location: http://www.supersaas.com/api/users/1234.xml. 作られたオブジェクトのSuperSaaS ID (1234)を見つけたいのであれば、このURLから見つけ出すことができます。 オブジェクトがバリデーションをパスしなかったのであれば、おそらく電子メールアドレスが正しくないためで、エラーメッセージを含むステータス422 ("Unprocessable Entity")が返されます。 もしすでにあなた自身のキーを提供していて、そのキーがすでにデータベースにあるのでしたら、あなたのコールが代わりに更新されるはずです。 自動的に作られたり、更新と解釈されるのを防ぐには、 パラメーター"duplicate=raise"を追加します。そうすれば、ステータスコード422が代わりに帰ってきます。 注意が必要です。あなたのブッキングIDがピリオドを含んでいる場合は、それを正しく動作させるためには "/api/users?id={id}" としてそれを呼び出す必要があります。

一人のユーザーを読む

GET /api/users/{id}
そのIDが全部数字であるなら、それは我々のキーと思われます。そうでないなら、あなたのキーと考えられます。 もしそのIDがアルファベットでしたら、それはネームフィールドに保存されます。アルファベットのIDは、URLの不正キャラクターを防止するためにURIエンコードされたパラメーターとして送られます。例:/api/users?id=ab%25cd. ユーザーを示すXMLドキュメントのレスポンスボディーと一緒に404(”見つかりませんでした”)もしくは(”OK”)のレスポンスがあります。
<user>
   ...
</user>

すべてのユーザーを読む

GET /api/users
これは、あなたのアカウントのすべてのユーザーを示すXMLドキュメントと合わせて200(”OK")を戻します。 あなたが"/api/users?limit=500"のようなリミットパラメーターを追加しない限り、記録数は100に限られます。
<users>
   <user>
      ...
   </user>
   <user>
      ...
   </user>
</users>

ユーザーをアップデートする

PUT /api/users/{id}
システムは任意のID レコードを探し更新します。 ”作る”のAPIと同様に、XMLドキュメントあるいはURIエンコードされたパレメーターを送ると、結果は200(”OK")もしくはエラードキュメント付きの422となります。 レコードが見つからない場合は、システムはあなたが作りたいのだと勘違いしてしまいます。 自動的に新しいレコードを作るのを防ぐには、パラメーターとして"notfound=error"もしくは”notfound=ignore"を追加します。 存在しないSuperSaaS内部キーを使用としているのでしたら、404(”見つからず”)が常に返されます。 あなたが使用しているソフトウエアがHTTP PUT Verbを送るのをサポートしていないならば、単に通常のPOSTを代わりに返します。

ユーザーを削除する

DELETE /api/users/{id}
システムはデータベースにあるそのIDを探し、レコードを問題なく削除したならば200(”OK")を、あるいは、すでに存在してないならば400(”見つかりません”)を返します。 あなたが使用しているソフトウエアが、HTTP DELETE Verbを送れないならば、追加のパラメーターとして"_method=DELETE"を付けたPOSTをしなければなりません。

データフォーマット

あなたが送るフィールドは、Accessコントロールのスクリーンで設定できます。 ユーザーネームを除き、すべての値を選択でき、特になければ、デフォルトの値(通常はブランク)に設定されます。

FieldComment
nameRequiredユーザーネームは、最大50バイトです。もしあなたがメールアドレスをログインネームとして選択したならば、これがメールアドレスになるはずです。
emailOptionalユーザーのemailアドレス。もしemailアドレスをログイン名として使用している場合は無視
passwordOptionalユーザーのパスワード。 もしパスワードをログイン時に使用している場合
full-name, address, mobile, phoneOptionalこれらの属性のいずれかが存在する場合、それらはUTF-8でエンコードされた文字列として変更されずに保存されます。
countryOptional存在しないか2文字のISO 3166-1国名コードのどちらか
field-1, field-2,
super-field
Optional2つのカスタムフィールドおよびスーパーバイザフィールドの値、ユーザー・インタフェースに与える表示ラベルとは無関係。
creditOptionalクレジットレベルの設定 (デフォルトは 0)。支払い設定上で選択されたフォーマット。
roleOptional3つの値: レギュラーユーザー (デフォルト), 4: Superuser or -1: Blocked user

データを読み取る際に取得したXMLドキュメントは、上記のものに加え、次のフィールドが含まれます。:
FieldComment
idSuperSaaSによりこのユーザーに割り当てられた内部ID
fk外部キーを指定した場合あなたによってこのユーザに割り当てられたID
created-onUTCで作成されたこのユーザー時間

例示的な使用法

XMLを使用するコールのこの例は、SuperSaaSユーザーデータベース内に新しいユーザレコードを作成します。レコードには、あなた自身のデータベース内のデータベースキー567があります。:

POST /api/users/567fk.xml
あなたはベーシックHTTP認証を使い、あなたのアカウント名と、ヘッダーに記されたパスワードを送信します。また次の文体を送信します。:
<?xml version="1.0"?>
<user>
   <password>secret</password>
   <full-name>Full Name</full-name>
   <name>user@example.com</name>
</user>

これにより、 空文の201("Created")レスポンスが返信されます。もしあなたがクエリーパラメータを使用する場合、フィールドレーベル内のダッシュをアンダースコアに入れ替え、user[field]として入力してください。値は、URIエンコードをしてください。

以下は先と同じ模範コールですが、今回はクエリーパラメータを使用する場合です。:

POST /api/users/567fk?account=demo&password=secret&user[name]=user@example.com&user[password]=secret&user[full_name]=Full%20Name

トラブルシューティング


チュートリアルインデックスへ戻る