Difference between revisions of "登録 API"

From Second Life Wiki
Jump to navigation Jump to search
(updated reflecting the changes in these days)
m (moved RegAPI/ja to 登録 API)
 
(No difference)

Latest revision as of 02:04, 29 April 2010

概要

The Registration API (Reg API、登録 API) を使うと、Seclind Life ユーザの新規登録をあなたのページでできるようになり、登録後に人々を指定したロケーションに飛ばす以上のことができるようになります。誰かにアカウントを登録させてログイン時に指定したロケーションに到着させたい場合は、DirectSLURL を使ってください。

登録 API は単純なREST 形式のウェブサービスですLLSD XML 文書で情報を渡して、LLSD データを受け取ります。Linden Lab は LLSD の解析とエンコードのライブラリを Perl, PHP, Python, Ruby で提供しています。Reg API Examples を参照してください。

いくらかがんばってプログラミングすれば、登録 API でこのようなことができます。

  • アカウントを自分の土地限定にする。
  • カスタムの名前でアカウントを作成する (Linden Lab の特別な許可のもとで - Custom_Name_Program を参照)
  • 同じ場所から、またはあなたの組織のウェブサイトの一部として、会社や教育機関の複数の従業員や生徒を登録する。

重要な制約と条件が適用されます。

  • 登録手続き画面の一部で、あなたが要求する条件に加えて、Linden Lab の Terms of Service を提示しなければなりません。
  • 利用者が、あなたと関係をもつのとは別に、Linden Lab と関係をもつことになることを明示しなければなりません。
  • サイトが公開されている場合、ALT アカウントと登録認証に関する Linden Lab のポリシーに従うように登録手続き画面を運用しなければなりません。通常は、一般に公開された登録手続き画面に登録 API を使用することを許可しません。DirectSLURL が望ましい選択肢になるからです。

登録 API でできること

登録 API を使って、あなたのウェブサイトへの登録の過程で Second Life アカウントを作成します。Second Life の登録プロセスをカスタマイズして追加の情報を取得したり登録プロセスをフィットさせたりすることができます。ユーザが登録すると、一意の Second Life 名とパスワードを選択します。登録手続き画面は Linden Lab に Second Life での標準的な登録手続き画面で提供されるものと同じ情報を提供します。登録処理の最後で、訪問客は Second Life のクライアントをダウンロードし、インストールして起動しなければなりません。このとき、あなたのウェブサイトで作成したアカウントが登録され、Second Life をあなたが指定したロケーションで始めます。

登録 API を使ってできること:

  • Second Life の住人登録をあなたのウェブサイトから行って、彼らを追跡する。
  • カスタマイズされた商標のついた登録手続き画面を提供する。
  • Second Life グループに新しく登録した住人を追加する。
  • 最初に Second Life にログインしたときに、あなたが選択したロケーションに飛ばす。
  • アカウントを自分の土地限定にする。
  • Linden Lab が許可すれば、名前の選択を制限したり、カスタム名でアカウントを作成したりする。これらの権限は別々に請求しなければなりません。詳しい情報は、Custom Name Program を参照してください。
  • あなたの組織で、内部からのみアクセスされる登録手続き画面を提供する。例えばイントラネットの Web サイトなど。

登録 API についての詳しい情報は Working InWorld Blog の記事に載っています。 Pocket FAQ: Creating Your Private, Branded Workspace with Reg API

登録 API でできないこと

登録 API でできないのは:

  • 持ち物を提供したり、アタッチメントを作成したり、住人の容姿を制御したりすること。
  • ビューワの見た目を変更すること。
  • 自動的に SIM を振り分けること。代わりに、それぞれの地点にある LSL スクリプトから送信されたデータをもとに登録 API を使ってスタート地点を選択してください。

登録 API はあなたが所有していない土地をスタート地点に設定することを禁止してはいません。その土地を所有していない場合、到着地点のオーナーに、新しい住人をそこに到着させてよいか確認をとらなければなりません。

参加方法

申請前に、上記「重要な制約と条件」の章を読んでください。通常は、土地の限定、カスタム名、ログイン画面またはファイアウォールの向こうでの組織メンバーの登録手続きが含まれる場合にのみ申請を受理します。公開された登録手続きには DirectSLURL を使用しなければなりません。

ベータ登録 API プログラムに参加申請するには、Registration API Request Form を提出してください。Linden Lab は申請を審査後、Eメールであなたに連絡します。最近停止した登録 API のアカウントがある場合は、 RegAPI Renewal Form で再申請してください。

重要事項

KBcaution.png 重要 登録 API はベータプログラムで、上手に使うには熟練した技術が必要となります。Linden Lab は 現在、使い方についてのサポートまたは技術的アドバイスは行っておりません。
  • 登録 API のケイパビリティをもつアカウントは、ケイパビリティを受け取ってから 90 日以内に全くアカウントが作成されないと登録 API へのケイパビリティが削除されます。
  • 登録 API プログラムの参加者は必ず Linden Lab の API Terms Of Service を順守しなければなりません。

ディスカッションとサポート

  • 登録 API の質問は talk page に投稿してください。
  • RegAPI mailing list で、登録 API についての情報を共有したり、質問を送ったりしてください。
  • Linden Lab は登録 API の技術的サポートは行っていませんが、サードパーティーのプロバイダからサポートを購入することができます。Registration API Third Party Support を参照してください。

通常の手順

登録 API を使うために:

  1. Registration API Request Form を記入して提出します。Linden Lab はEメールで連絡します。
  2. capabilities form を使って自分のケイパビリティを確認します。
  3. ユーザがインワールドに現れる土地のオーナーに許可をとったか確認します。(Linden Lab のオリエンテーションアイランド以外の場所の) 土地のオーナーに 絶対に 許可をとってください。複数の登録画面をもっていて、複数の地点に人々を飛ばす必要のあるときは、私たちに連絡して追加の指示を受けてください。
  4. 登録 Web 画面を作ります。
  5. PHP を使っている場合、ライブラリがインストールされていて動作していることを確認します (http://uk.php.net/phpinfo を参照のこと)。
  6. 登録アプリケーションをテストします。
    • ユーザを何人か登録します。
    • 期待した結果が返ってこない場合、error code を確認します。
    • ありふれた エラーコード をテストする登録画面を作って、エラーコードを受け取って適切に処理できることを確認します。

テストの際には

登録 API をメイングリッドに登録するために使う場合、18 歳未満のユーザは登録できません。メイングリッドで許可されていないからです。このため、テスト時には、登録者が 18 歳以上となる誕生日を使用してください。

Second Life に現在存在しないEメールアドレスを使用してください。ユーザがEメールアドレスを既に登録してある場合、登録 API はエラーコード 95, email exists エラーを返します。エラーに引っ掛かったら、このエラーコードを見ることになりますが、そうでなければ、登録手続きは落ちます。

ケイパビリティ URL を使用する

登録 API ケイパビリティ は特定のアクションを実行する権限を意味します。登録 API はケイパビリティを 以下の書式のケイパビリティ URL で与えます。

https://cap.secondlife.com/cap/0/UUID

UUID のところは特定のケイパビリティを与えられた UUID (universally unique identifier) です。

例:

https://cap.secondlife.com/cap/0/2897456b-6959-473e-9b94-36d8cec1b9c3

登録 API はケイパビリティ URL を次のような操作で与えます。

  • add_to_group - Second Life グループに新しいユーザを追加する。
  • create_user - 新しいユーザを作成する。
  • check_name - ユーザが指定した Second Life のファーストネームとラストネームで登録できるか表示する。
  • get_last_names - 新しいユーザを登録できるラストネームと対応する ID を返す。
  • get_error_codes - エラーコード一式を取得する。

これらの操作の詳しい情報は、Registration API Reference を参照してください。

例えば、Second Life ウェブサイトで提供されている example capabilities form をよく見てください。あなたに現在付与されているケイパビリティを記述するようになっています。

フォームはあなたの「ファーストネーム」、「ラストネーム」、「パスワード」を https://cap.secondlife.com/get_reg_capabilities に POST で送信してケイパビリティを取得します。正確な HTML はこのようになります:

<html4strict><form action="https://cap.secondlife.com/get_reg_capabilities" method="POST">

First Name<input name='first_name'>
Last Name<input name='last_name'>
Password<input name='password' type='password'>
 
<input type='submit' value="Get Capabilities">

</form></html4strict>

このようなフォームを送信したら、登録 API はこのような XML 文書を返します:

<xml><llsd>

 <map>
   <key>get_error_codes</key>
   <string>https://cap.secondlife.com/cap/0/e2fd05e0-d4f0-4f04-8805-fdc1bd4e9ea2</string>
 </map>

</llsd></xml>

この例ではあなたが "get_error_codes" ケイパビリティをもっていることを示しています。代わりにもっとケイパビリティが与えられていたとしたら、文書はこのような感じになっていたことでしょう:

<xml><llsd>

 <map>
   <key>create_user</key>
   <string>https://cap.secondlife.com/cap/0/35ff3b8c-a30d-4d18-b29a-e3f7f6c79cb6</string>
   
   <key>check_name</key>
   <string>https://cap.secondlife.com/cap/0/6e528ba1-a8b0-4f6b-8b56-362ee6f5cef8</string>
   
   <key>get_last_names</key>
   <string>https://cap.secondlife.com/cap/0/be4e4d2e-c00a-46cd-bb8d-d17cb8e92c9b</string>
   
   <key>get_error_codes</key>
   <string>https://cap.secondlife.com/cap/0/e75f81a5-b7da-4480-8f95-b1cf9d2d680f</string>
 </map>

</llsd></xml>

もちろん、例のケイパビリティ URL は実際には動作しません。

登録 API で LLSD を使用する

LLSD XML データフォーマットを使って、ケイパビリティ URL からの情報の送信・取得を行います。ここに典型的な LLSD XML メッセージの例を載せます:

<xml><llsd>

  <map>
    <key>dob</key><string>1987-07-06</string>
    <key>start_region_name</key><string>da boom</string>
    <key>username</key><string>mistaht</string>
    <key>last_name_id</key><integer>1872</integer>
    <key>password</key><string>123456</string>
    <key>email</key><string>ben@ben.com</string>
  </map>
</llsd></xml>

この文書は (ハッシュ) マップとなっており、キーは:

  • dob
  • start_region_name
  • username
  • last_name_id
  • password
  • email

です。

この文書は新しいユーザを作成するために "create_user" をケイパビリティ URL に POST する典型的な LLSD XML メッセージです。

この LLSD 仕様はさまざまなデータタイプの仕様を定めています: Map, Array, String, Integer, Float, Date など。それぞれのデータタイプはほとんどの言語の基本データ型に対応しています。

LLSD XML ライブラリはネイティブなオブジェクトを LLSD XML にエンコードするなどの作業の大半を行います。例えば、Ruby ライブラリを次のように使うことができます:

require 'LLSD'

native_obj = 123
llsd_xml = LLSD.to_xml(native_obj) # returns <llsd><integer>123</integer></llsd>
returned_native_obj = LLSD.parse(llsd_xml) # ネイティブの ruby integer, 123 を返す

LLSD のエンコードとデコードで問題があったら、送受信された実際の LLSD XML を見てデバッグに着手しましょう。

アカウントを土地に限定する

登録 API で登録者をレジスタ (登録手続きを制御するアカウント) の土地に制限することができます。アカウントを作成するときに、limited_to_estate パラメタに土地の ID を使用しなければなりません。詳細は、create_user を参照してください。

土地のコードを知るためには (2009 年 3 月 16 日現在):

  1. Ctrl-Alt-⇧ Shift-D を押して、追加のプルダウンAdvanced メニューを出します。
  2. それから Advanced > View Admin Options (下のほう) へ。
  3. Admin の新しいプルダウンメニューから、God Tools を選択します。
  4. Region タブを見ます。土地の ID がそこにリストで表示されています。

土地にアクセスできないアカウント

登録手続きを「土地限定」にして、人々があなたの土地に入れず、アクセス制御でグループメンバーしか土地に入れないことになっていることが発覚した場合、まず新しいユーザをを必要なグループに追加して、あなたの土地に入れるようにしなければなりません。

他の方法として、土地を分割して制限がない土地を作成し、そこに到着エリアを設定し、新しいユーザをグループに追加して残りの土地へのアクセスができるようにすることもできます。

ガイドラインとヒント

  • 必ず登録 API がアカウントを作成できるアカウントを使ってください。
  • 追加アカウントを作成するときは、ビューワや secondlife.com 登録画面でなく、登録 API を使用しなければいけません。
  • (What are Capability URLs で取得できる) ケイパビリティ URL にあなたの ケイパビリティを含め、あなたのアカウントとロケーションをスクリプトに追加したか点検しましょう。
  • エラーコード を確認しましょう。
  • 追加情報やトラブルシューティングの助けを受けるために、登録 API メーリングリストに参加しましょう

ケイパビリティ URL を使用するときには、以下のガイドラインに従ってください:

  • 返されたエラーコードを拾って表示するコードを追加します。これは問題のトラブルシューティングで役に立ちます。
  • ケイパビリティ URL をハードコーディングしないでください。ケイパビリティ URL を定数としてコーディングするか、できれば、実行時に取得するようにします。ケイパビリティ URL はいつかは有効期限が切れますので、新しいものがいつも良いです。
  • ケイパビリティ URL は秘密にしてください!あなたに与えられたケイパビリティはあなただけのものです。ケイパビリティ URL はパスワードと同じように慎重に扱うべきものです。さらに、Linden Lab はそれぞれのケイパビリティの使い方を追跡しています。

PHP を使用している時:

  • LLSD ライブラリは PHP5 でテストされておらず、多くのありふれた PHP5 の設定では動かないことが知られています。PHP4 と PHP5 で互換性のある、改良したバージョンをすぐに使えるようにするつもりでいます。それまでの間、PHP5 を使用しなければならないのであれば、このアダプタを使用して成功したという報告があります: http://alexandre.alapetite.net/doc-alex/domxml-php4-php5/
  • デンジャラスに生きたいのであれば、RegAPI_for_PHP5 を試してみてください。
  • Curl ライブラリがインストールされ起動していることを確認してください。