LSL HTTP server/ja

From Second Life Wiki
< LSL HTTP server
Revision as of 04:20, 10 April 2010 by Mako Nozaki (talk | contribs) (カテゴリ変更)
Jump to navigation Jump to search

まえがき

これは llHTTPRequest の対となるものです。llHTTPRequest によって LSL スクリプトが HTTP でアクセスできる情報源にデータをリクエストすることができますが、 HTTP-in は外の情報源がセカンドライフ内のスクリプトにデータをリクエストできるようになります。その差は、llHTTPRequest が SL 内のスクリプトが欲しいときに情報交換するのに対し、HTTP-in は外の情報源の都合により SL 内のスクリプトとコミュニケーションすることができるということです。

HTTP-in ができるまでは、同じような機能はllHTTPRequest や llEmail や XML-RPC によるポーリングによって実現されていました。3 つとも扱いにくく、最後の 2 つは拡張性の上で深刻なボトルネックとなっていました。

気をつけたい重要な点は、LSL HTTP サーバが HTML を扱えないことです。詳細は、Other Limitations を参照してください。

使用場面

  • LSL スクリプトからデータを取得し、外部ビューア、スクリプト、サーバに送ることが簡単にできます。
    • ビジターカウンターやその他統計収集装置の Web フロントエンドに。
  • 外部ビューア、スクリプト、サーバから LSL スクリプトにデータを送ることが簡単にできます。
    • インワールドのオブジェクトと通信して、L$ やインベントリアイテムをやりとりする Web フロントエンドがある店舗。
    • 外部プログラムがインワールドのアイテムを操作する必要のある重要なゲームロジックを握っているインワールドゲーム。

どろどろとした技術的な詳細は次項にて。もしくは、 Script Examples まで読み飛ばしてください。

スクリプト API

新しい LSL サーバ公開 URL をリクエストします。
成功または失敗と、取得されたキーで、http_request イベントが発生します。
注意: URL は呼び出し元スクリプトに割り当てられています。http_request イベントは URL をリクエストしたスクリプトとは異なるスクリプトからは発生しません。

<lsl>request_id = llRequestURL();</lsl>

HTTPS / SSL URL をリクエストする点以外は、llRequestURL とほぼ同じです。
成功または失敗と、取得されたキーで、http_request イベントが発生します。

<lsl>request_id = llRequestSecureURL();</lsl>

指定された URL を消去します。セキュアな URL にもセキュアでない URL にも使えます。

<lsl>llReleaseURL("http://sim3015.aditi.lindenlab.com:12046/cap/3ff4f3f2-ea08-76c1-cef6-a22b4a573a7c");</lsl>

URL がヒットしたときに発生するイベントです。
  • id はリクエストごとに違います。
  • サポートされるメソッドは、GET/POST/PUT/DELETE です。
  • body: リクエストの内容。
イベントは llRequestURL や llRequestSecureURL へのレスポンスでも発生します。
  • id は llRequestURL や llRequestSecureURL で返却されたキーと一致します。
  • method == URL_REQUEST_GRANTED は成功していますが、 URL_REQUEST_DENIED は URL の取得に失敗しています。
  • body は公開 URL です。公開 URL の取得に失敗した場合は、空です。
リクエスト元の body にステータスコードを status で返します。
  • id は特定のリクエストに関連づけられた http_request の ID です。
  • リクエスト元にレスポンスを送信すると、リクエストを消去し、関連した情報を削除します。
指定されたリクエストの指定されたヘッダの文字列を返却します。受信されたヘッダは全て小文字に変換され、この関数は大文字小文字を区別します。返却される文字列は 255 文字までです。
  • サポートされるヘッダ:
  • "x-script-url": llRequestURL または llRequestSecureURLから取得したベース URL
  • "x-path-info": リクエスト先 URL の後続パスの情報
  • "x-query-string": クエリ引数、URL の最初に現れる "?" に続くテキスト文字列
  • "x-remote-ip": リクエストを生成したホストの IP アドレス
  • "user-agent": リクエスト元から通知された user-agent
  • "x-secondlife-shard"
  • "x-secondlife-object-name"
  • "x-secondlife-object-key"
  • "x-secondlife-region"
  • "x-secondlife-local-position"
  • "x-secondlife-local-rotation"
  • "x-secondlife-local-velocity"
  • "x-secondlife-owner-name"
  • "x-secondlife-owner-key"
requested url: https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322/foo/bar?arg=gra
x-script-url: https://sim3015.aditi.lindenlab.com:12043/cap/a7717681-2c04-e4ac-35e3-1f01c9861322
x-path-info: /foo/bar
x-query-string: arg=gra
ヘッダ情報は 30 秒間か、llHTTPResponse が呼び出されるまで有効です。
  • CHANGED_REGION_START: 地域が再起動されたときに呼び出される新しい changed() イベントです。
スクリプトで使用できる URL の数を返します。

URL 生存時間の制限

  • URL は 一時的 なものです！
  • URL は以下の場合は消えることがあります。併記したスクリプトイベントで全て検出可能です。
  • URL が「消失」した場合、スクリプトの全ての公開 URL が消失しています。新しい URL をリクエストする必要があり、新しい URL は以前のと 似ても似つかない ものになります。
  • URL を永続化するには、Dynamic DNS がドメイン名と動的 IP アドレスを関連づけるのと同じような仕組みで動くような外部サービスを構築するか利用する必要が出てきます。

寄贈された HTTP-in URL マッピングの実装やサービス:

  • Google App Engine 上で動作する動的 DNS サービス (サンプルとして提供されました)。ここのフォーラムで見つけることができます。
  • Virtual ID URLMap service はユーザが選んだ固定サブドメインのマッピングを REST API (一部無料 Apez Corp web-services API) を通じて行ってくれます。
  • まだ他には、GAE の上で、パスワードで保護されたプライベートドメインで運用する方法があります。http://wiki.secondlife.com/wiki/Public_Object_DNS

Resource Limitations

  • There are a limited number of URLs available in each region, split by land ownership exactly like prim limits.
    • Use llGetFreeURLs to get the exact number of available URLs for the script.
    • The number of allowed URLs is the same as the number of allowed prims on the parcel the object is over.
      Object owner does not matter, all objects over a parcel will use the resource pool for that parcel.
      Like prims, all the parcels owned by the same owner and in the same region share the same pool of resources.
      If you have two parcels in a region that each support 100 URLs, then you could use all 200 in object(s) on a single parcel.
    • The region's object bonus factor does not apply to available URLs.
      If a parcel has a max of 300 prims in a region with a 2x bonus factor there will only be 150 urls allowed.
  • Each resident has their own unique pool of available URLs with a max of 38 URLs per resident.
    • This is 1 per attachment point, but all 38 could be used by a single attachment for example.
  • Vehicles are special and lazily moved to resident pools by the following logic:
    • Any object that has a resident sitting on it is a 'vehicle'
    • Vehicles will use the url resources from the parcel they are over until the cross a parcel border.
      Specifically this prevents anyone from breaking your vending machine by sitting on it and making it a 'vehicle'.
    • When any object using URL resources with a resident sitting on it crosses a parcel boundary the resources will switch to the first sitting resident with enough resources. If no sitting agents have enough resources then the resources from the parcel being moved onto will be used. If even then there are not enough resources to use then the vehicle will be blocked from moving.
      In short we do everything we can to find a pool to host the resources needed by the vehicle, but will block movement if we can't.
  • Parcel Sale: When a parcel is sold such that it changes the total available URLs in the region for either resident (seller or buyer) such that more URLs are being used than are available some objects will be returned.
    • The objects returned will be from youngest object to oldest object of those using URLs in each category in order of object category: Temporary, Other, Group, Owner, Selected/Sat upon.
      The only time objects are possibly returned is when parcels change owner, and only if more resources are being used than allowed.
      We return youngest temporary objects before older temporary objects before younger 'other' (owned by non-group, non-parcel-owner) objects etc.

Other Limitations

  • Size of the body of the requests will be limited to 2k bytes.
  • Size of headers of requests will be limited to 255 bytes. This is per header, not total.
  • The size of responses to requests is not currently limited, but this is subject to review during testing.
  • The content type of the returned data is always 'text/plain; charset=utf-8'
    Allowing more content type options is a possibility for the future, but not guaranteed.
  • There is a cap of 64 in flight requests per script. This is based on the maximum number of pending events in LSL. After hitting the 64 request limit, the simulator cap server returns '503 Service Unavailable' to the inbound request.
  • We may throttle the rate we accept hits at the CAP server level as well. This is possible, but has not yet been decided.
  • HTML cannot be used without an external parser, as all output is plain text only. If making such a parser, remember that you should probably restrict access to only Linden Lab HTML URLs as to not have your bandwith stolen.
  • It is important to note that when appending a query string to a cap URL there MUST be a trailing slash between the cap guid and the query string token '?'. IE https://sim123.agni.lindenlab.com/cap/f73b4b94-012d-44f2-bd0c-16c328321221?arg=gra will return an HTTP 500, but https://sim123.agni.lindenlab.com/cap/f73b4b94-012d-44f2-bd0c-16c328321221/?arg=gra will succeed. (This doesn't seem to be true.)

Links

Retrieved from "https://wiki.secondlife.com/w/index.php?title=LSL_HTTP_server/ja&oldid=848802"