PR
連載 [第1回] :
  PerlでWeb APIを使いたおす

Web APIの紹介

2006年9月27日(水)
水野 貴明

XML-RPCの仕組み


   この記事では、Web APIの標準的な仕様としてよく利用されているものをいくつか取り上げ、その仕組みや利用方法を紹介していくことにします。まずはXML-RPCです。

   XML-RPCは、名前を見てもわかるとおり、データとしてXMLを利用するWeb APIの仕様です。RPCはRemote Procedure Callの略です。XMLを利用して、ネットワーク越しにプロシージャ、つまり何らかの処理を呼び出すものである、という仕組みをそのまま名前にしています。

   XML-RPCは、米Userland社が1998年に自社のWebサイト管理ツールであるFrontierで利用するために策定した仕様であり、策定者は当時Userland社の社長を務めていたDave Winer氏です。Winer氏はRSS 0.91やRSS 2.0の仕様策定にも関わった人としても有名です。

   XML-RPCは比較的古くからある仕様ではありますが、シンプルで使いやすいので、現在でも利用されています。例えばブログのサービス/ツールであるBloggerやMovable Typeなどは、ブログの記事を取得したり更新するためのAPIとして採用しています。

   まずはXML-RPCの仕様を簡単に見ていくことにしましょう。XML-RPCを利用したAPIでは、アクセスするためのエントリポイントとなるURLが用意されています。このURLに対してアクセスすることで、処理を実行するわけです。

   XML-RPCでは1つのエントリポイントを使って複数のメソッドを提供できます。アクセスの際にはメソッド名とパラメータを渡します。パラメータは文字列や数値、配列など、プログラムにおける通常のサブルーチン呼び出しと同じようなものが利用できます(当たり前ですが異なるコンピュータ上で処理を行うので、メモリ参照を渡すことはできません)。すると処理の結果を戻り値として取得できます。戻り値としては複数の値をとることはできないというルールになっていますが、実際には戻り値を配列にすることで、複数の値(例えばブログのエントリのURLとタイトル、コンテンツなど)を返すこともできます。

   クライアントからサーバーへのアクセスには、HTTPのPOSTメソッドを利用します。送受信する情報はXMLで、リクエストとレスポンスにおけるボディとして送受信されます。まずはリクエストのサンプルをリスト3に示します。
リスト3:XML-RPCのリクエストサンプル
POST /RPC2 HTTP/1.0
User-Agent: ExampleClient/1.0
Host: api.example.com
Content-Type: text/xml
Content-length: 255
<?xml version="1.0"?>
<methodCall>
<methodName>example.getUser</methodName>
  <params>
    <param>
      <value><i4>23456</i4></value>
    </param>
    <param>
      <value><boolean>1</boolean></value>
    </param>
  </params>
</methodCall>

   このサンプルはヘッダーとボディをすべて含むリクエストの全データです。リクエストヘッダーにおいては、「User-Agent」、「Host」、「Content-Type」、「Content-Length」が必須ということになっています。Content-Typeは「text/xml」です。

   実際のデータは簡単な構造なので、見ればだいたい察しがつくのではないでしょうか。データ全体はmethodCallというルート要素になっており、その中にメソッド名を示すmethodNameと渡すパラメータを示すparams、そしてその中にはデータをあらわすvalue要素が入ります。

   value要素に指定できる値はさまざまで、その値の種類ごとに要素が定義されています。例えば文字列ならstring、真偽値ならbooleanといった具合です(型の指定を省略するとstringとみなされます)。利用可能なデータ型を表1に示します。

種類
i4、int 4バイト符号付き整数
boolean 真偽値(1が真、0が偽)
string 文字列
double 倍精度浮動小数
dateTime.iso8601 日付と時刻(ISO-8601形式)
base64 BASE64エンコードされたバイナリ
array 配列
struct 構造体

表1:XML-RPCの型

   配列を表すarrayと、構造体(ハッシュのような名前とデータの組)を表すstructが複数の値を持つデータ型で、それ以外は単一のデータを表します。バイナリデータを送受信する際にはBASE64でエンコードすることになります。

   リスト4にarrayとstructのサンプルを示します。

リスト4:arrayとstructのサンプル
◆array
<array>
  <data>
    <value><string>apple</syring></value>
    <value><i4>40</i4></value>
    <value><boolean>1</boolean></value>
  </data>
</array>

◆struct
<struct>
  <member>
    <name>userid</name>
    <value><i4>2342</i4></value>
  </member>
  <member>
    <name>username</name>
    <value><string>Taro Yamada</string></value>
  </member>
</struct>

   arrayは単にvalueが列挙されるだけですが、structはmemberという要素を用いて、複数のデータを列挙します。データ名はname要素に、実際のデータはvalue要素に入ります。

   どちらも異なるデータ型のデータをまとめることができ、arrayやstructの中にarrayやstructを内包させることも可能です。なお、struct型ではmemberの順番は保持されません。

   さて、送信したリクエストが正しく処理がされれば、サーバーからXMLを使ったレスポンスデータが返ってきます(リスト5)。

リスト5:レスポンスデータの例
HTTP/1.1 200 OK
Content-Length: 163
Content-Type: text/xml

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value><string>Taro Yamada</string></value>
    </param>
  </params>
</methodResponse>

   レスポンスデータの場合は、ルート要素がmethodResponseになります。その中には1つのparams要素があり、その中に1つのparam要素が含まれます。ここに2つ以上param要素を入れることはできません。しかしarrayやstructを返すことで、複数の値を返すことは可能です。

   もし、サーバーが処理をした際にエラーが発生した場合は、paramsの代わりにfault要素を入れることになっています(リスト6)。

リスト6:エラーレスポンスデータの例
HTTP/1.1 200 OK
Content-Length: 426
Content-Type: text/xml

<?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>

   エラーの場合でも、XML-RPCの処理中で発生したエラーであれば、ステータスコードは200になります。faultの場合は、データとしてはstruct型を返し、そこに含まれる要素はエラーコードを示すfaultCodeと、エラーの内容を示すfaultStringを含めることが決められています。

   これがXML-RPCの仕様になります。かなりシンプルな仕様だなあ、という印象ではないでしょうか。XML-RPCが規定するのは、サブルーチンを利用することに置き換えれば、パラメータを渡して呼び出す部分と、戻り値を受け取る部分にすぎません。XML-RPCでは、それに必要な最低限のルールを規定しているのにすぎないのです。

1973年東京生まれ。エンジニア兼技術系ライター。株式会社はてな勤務。近著に「俺流Amazonの作り方」(アスキー)、「詳解RSS〜RSSを利用したサービスの理論と実践」(ディー・アート)など。趣味はラテン音楽と海外旅行と神輿。現在、家を荒らしまわるネズミの被害に頭を悩ませている。

連載バックナンバー

Think IT会員サービス無料登録受付中

Think ITでは、より付加価値の高いコンテンツを会員サービスとして提供しています。会員登録を済ませてThink ITのWebサイトにログインすることでさまざまな限定特典を入手できるようになります。

Think IT会員サービスの概要とメリットをチェック

他にもこの記事が読まれています

Web APIの紹介 | Think IT(シンクイット)

Think IT(シンクイット)

サイトに予期せぬエラーが起こりました。しばらくたってから再度お試しください。