 |
 |
Perlで作るCGI講座 |  |
 |
|
英語技術文書日本語訳 |  |
|
|
|
|
|
|
|
|||||||||
|
|
|
|
|
||||||||||
|
||||||||||||||
|
本ドキュメントは、UserLand Software, Inc. が公開している 『XML-RPC Specification』 を futomi が日本語化したものです。みなさまの理解に役立てれば幸いです。なお、緑色で記載された文章は、futomi が注釈として加筆したものです。また、一部、直訳ではなく、意訳した部分がございます。原文と表現が異なることがございますので、ご了承ください。
注意: この日本語訳は、futomi が理解を深めるために、自分なりに日本語化したものです。本日本語訳には、翻訳上の誤りがある可能性があります。したがって、内容について一切保証をするものではありません。正確さを求める場合には、必ず原文を参照してください。当方は、この文書によって利用者が被るいかなる損害の責任を負いません。
もし誤りなどを見つけたら、こちらからご連絡いただければ幸いです。
Tue, Jun 15, 1999; by Dave Winer.
この仕様は、UserLand Frontier 5.1 に実装されている XML-RPC プロトコルを説明するものです。
技術に関係の無い説明に関しては、XML-RPC for Newbies をご覧下さい。
このページは、実装者が必要とする情報を漏れなく提供します。
XML-RPC は、インターネット上で動作する Remote Procedure Calling プロトコルです。
XML-RPC メッセージは、HTTP-POST リクエストです。リクエストのボディーは XML です。プロシージャーはサーバー上で実行され、それが返す値もまた XML で整形されています。
プロシージャーのパラメータには、スカラー、数字、文字列、日付などがありますが、複雑なレコードやリスト構造でもかまいません。
XML-RPC リクエストの例です。
POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181
<?xml version="1.0"?>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>41</i4></value>
</param>
</params>
</methodCall>
ヘッダーの最初の行にある URI のフォーマットは規定されておりません。例えば、サーバが XML-RPC コールをハンドリングさえすれば、それは空白でも構いませんし、一つのスラッシュでも構いません。しかし、サーバが HTTP リクエストを同時にいくつもハンドリングしているならば、URI は XML-RPC リクエストをハンドリングするコードへのリクエストを送る手助けになります。（前述のサンプルでは、URI が /RPC2 となっており、サーバに "RPC2" レスポンダーへリクエストを送るようにと伝えているのです。）
User-Agent と ホストは指定しなければいけません。
Content-Type は text/xml です。
Content-Length は指定しなければいけませんし、それは正確な値でなければいけません。
ペイロードは XML の中にあり、単一の <methodCall> 構造から成ります。
<methodCall> には、<methodName> 子要素を含めなければいけません。これは文字列であり、呼び出されるメソッドの名前が入っています。その文字列には、識別子の文字が入っているだけかもしれません。使える文字は、A-Z の大文字・小文字、0-9 の数字、アンダースコアー、ドット、コロン、スラッシュです。methodName 内の文字を解釈する方法を決めることは、完全にサーバの仕事です。
例えば、methodName は送られてくるリクエストで実行するスクリプトが入っているファイルの名前かもしれませんし、データベーステーブル内のセル名かもしれません。もしくは、フォルダやファイルの階層の中に入っているファイルへのパスかもしれません。
プロシージャーコールにパラメータがある場合には、<methodCall> に <params> 子要素を入れなければいけません。 <params> 子要素には、 <value> 要素を持つ <param> 要素をどれだけ入れても構いません。
<value> はスカラーで、下表に掲載されているタグの一つの中の値をネストすることによってタイプが示されます。
| タグ | タイプ | 例 |
| <i4> or <int> | 4 バイト符号付整数 | -12 |
| <boolean> | 0 (偽) または 1 (真) | 1 |
| <string> | 文字列 | hello world |
| <double> | 倍精度符号付浮動小数点数 | -12.214 |
| <dateTime.iso8601> | 日付/時間 | 19980717T14:08:55 |
| <base64> | base64 エンコード済みバイナリー | eW91IGNhbid0IHJlYWQgdGhpcyE= |
もしタイプが指定されなければ、そのタイプは文字列です。
一つの値は、<struct> のタイプにもなりえます。
<struct> は <member> を含み、各 <member> は一つの <name> と一つの <value> を含みます。
2 つの要素を持った <struct> の例は次の通りです。
<struct>
<member>
<name>lowerBound</name>
<value><i4>18</i4></value>
</member>
<member>
<name>upperBound</name>
<value><i4>139</i4></value>
</member>
</struct>
<struct> は繰り返し利用することができます。以下で説明されているように、<value> には、<array> を入れることで <struct> やその他のタイプを入れても構いません。
一つの値は、<array> のタイプにもなりえます。
<array> は <data> 要素を一つだけ含みます。<data> 要素は、いくつかの <value> を含みます。
4 つの要素配列の例は次の通りです。
<array>
<data>
<value><i4>12</i4></value>
<value><string>Egypt</string></value>
<value><boolean>0</boolean></value>
<value><i4>-31</i4></value>
</data>
</array>
<array> 要素には名前がありません。
あなたは、上記の例に示すようにタイプをミックスすることができます。
<array> は繰り返し利用でき、前述の通り、valueには、<struct> を入れることで、<array> やその他のタイプを入れても構いません。
XML-RPC リクエストのレスポンスの例を挙げます。
HTTP/1.1 200 OK
Connection: close
Content-Length: 158
Content-Type: text/xml
Date: Fri, 17 Jul 1998 19:55:08 GMT
Server: UserLand Frontier/5.1.2-WinNT
<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><string>South Dakota</string></value>
</param>
</params>
</methodResponse>
低レベルエラーが無い限り、常に 200 OK を返します。
Content-Type は text/xml です。Content-Length は必須で、その値は正しくなければいけません。
レスポンスのボディーは、単一の XML 構造体で <methodResponse> です。これは、単一の <params> を含むことができます。<params> は、単一の <value> を含む単一の <param> を含みます。
<methodResponse> には <fault> を入れることができます。<fault> には <faultCode> と命名された <int> 要素と、<faultString> と命名された <string> 要素の 2 つの要素を持った <value> 要素が入ります。
<methodResponse> には <fault> と <params> を一緒に入れることはできません。
HTTP/1.1 200 OK
Connection: close
Content-Length: 426
Content-Type: text/xml
Date: Fri, 17 Jul 1998 19:55:02 GMT
Server: UserLand Frontier/5.1.2-WinNT
<?xml version="1.0"?>
<methodResponse>
<fault>
<value>
<struct>
<member>
<name>faultCode</name>
<value><int>4</int></value>
</member>
<member>
<name>faultString</name>
<value><string>Too many parameters.</string></value>
</member>
</struct>
</value>
</fault>
</methodResponse>
ファイアーウォール： このプロトコルの最終目標は、異なる環境間で互換性のある基盤を構築することです。新規の能力が CGI インタフェースの能力を超えて提供されることはありません。ファイアーウォールソフトウェアは、Content-Type が text/xml となっている POST に対して監視することができます。
発見性： 我々は、不要なものがない拡張可能なフォーマットを求めていました。それはとてもシンプルなものです。XML-RPC プロシージャーコールを含むファイルをみて、それが何をしているのかを理解でき、そして、それを変更することができ、それが1 回か 2 回の試みで動作できるようにすることは、HTML コーダーにとって可能にしなければいけません。
実装の簡易性： 我々は、他の環境や他のオペレーシングシステム上で実行できるよう速やかに適合することができるプロトコルを、簡単に実装できるようにしたいと考えています。
XML-RPC が Python に実装されていたとき、UserLand のディスカッショングループに次の質問が投げかけられました。
string の定義から "ASCII" を削除しました。
下記の通り、著作権表示に日付を 1998-99 から1999-2003 に変更しました。
© Copyright 1998-2003 UserLand Software. All Rights Reserved.
この文書と、この文書の翻訳は、複製したり、他に提供しても構いません。そして、それにコメントしたり、そうでなければそれを説明したり、もしくは、その実装を手助けするような派生の作業が、全部もしくは一部で、準備され、複製され、出版され、配布されても構いません。いかなる制限もありませんが、上記の著作権表示を提供して下さい。そして、これらの文章をそのような複製や派生作業のすべてに含めて下さい。
著作権表示や、UuserLand や他の組織への参照を削除するなどして、この文書を決して変更してはいけません。さらに、これらの著作権表示が XML-RPC 仕様に適用されますが、UserLand はそれに記述されるプロトコルに対して所有権の主張をすることはありません。いかなる団体も、商用であれ、非商用であれ、著作権使用料やライセンス料を UserLand に支払うことなく、このプロトコルを実装することができます。ここで承諾される限定的な許諾は永久的であり、UserLand やその継承者や譲受人によって取り消されることはありません。
この文書とここに込められれている情報は、"AS IS"（現状のまま）原則に基づき提供されます。明示・黙示を問わず、そこにある情報の利用が、いかなる権利やいかなる市場性の暗黙の保証や特定用途への適正を侵害することがないという保証を含むがこれに限定されない、いかなる保証の責任を UserLand は負いません。
 |
||||||||||||||
 |
|
 |
||||||||||||
