ochalog

RubyとMediaWikiとIRCが好き。

Hiki の XML-RPC インターフェース

Hiki Ruby プログラミング

Hiki2MediaWiki Auto で XML-RPC インターフェースを利用して Hiki を更新する機能を実装したのだけれど、Hiki の XML-RPC インターフェースについてのまとまった情報が見つからなくて苦労したので、ここにまとめてみる。

XML-RPC とは

XML-RPC とは、HTTP の POST メソッド経由で XML をやりとりして リモートホストのプロシージャを呼び出す仕組みです。

「Rubyist Magazine - 標準添付ライブラリ紹介 【第 1 回】 XMLRPC4R#XML-RPCとは?」より

Hiki でこれを使うと、以下のことを自動的に行える。

  • ページの Hiki ソースの取得
  • ページの情報の取得
  • ページの編集
  • すべてのページ名の取得

Ruby で XML-RPC を発行する方法

xml-rpc/client ライブラリを使う。エラー処理を含めた例は以下のような感じ。

require 'xmlrpc/client'
 
client = XMLRPC::Client.new2('http://example.com/hiki/')
begin
  result = client.call('wiki.someMethod', arg1, arg2)
rescue XMLRPC::FaultException => e
  STDERR.puts("Error: #{e.faultCode}: #{e.faultString}")
end

Hiki の XML-RPC インターフェース

hiki/xmlrpc.rb を参考にまとめた。

Hiki の XML-RPC インターフェースは「WikiRPC - wikiのためのXMLRPCインターフェイス。」を参考に実装されているらしい（「Wikiで作ろうWeb雑誌！―『るびま』作りの舞台裏」（PDF）より）。

文字列の扱いに関しては次の節で。

wiki.getPage(page) -> String

ページの Hiki ソースを返す。

引数
  • page
    • ページ名を表す String を指定する。ここでの「ページ名」は URL で見える、つまりページを作成したときのページ名。後から日本語などで付け直した名前は「タイトル」として区別される。以下同様。
戻り値

ページの Hiki ソースを表す String を返す。

例外
  • XMLRPC::FaultException (1: No such page was found.)
    • 指定した名前のページが見つからないと発生する。

wiki.getPageInfo(page) -> Hash

ページの情報を含むハッシュを返す。

引数
  • page
    • ページ名を表す String を指定する。
戻り値

ページの情報を含む Hash を返す。キーと値は以下の通り。

  • "title"
    • ページのタイトルを表す String。
  • "keyword"
    • ページのキーワードを表す String を要素として持つ Array。
  • "md5hex"
  • "lastModified"
    • ページの最終更新日時を表す Time。UTC。
  • "author"
    • ページの編集者を表す String。指定されていなければ空文字列。

wiki.putPage(page, content, attributes) -> bool

ページを編集する。ページが存在しない場合には新しく作成する。

引数
  • page
    • ページ名を表す String を指定する。
  • content
    • ページの Hiki ソースを表す String を指定する。
  • attributes
    • ページ更新に関するその他の情報を表す Hash を指定する。特に指定する必要がない場合は nil か {} を渡せばよい（省略はできない）。主なキーと値は以下の通り。
    • "name"
      • ログイン時のユーザ名を表す String。
    • "password"
      • ログイン時のパスワードを表す String。
    • "minoredit"
      • 細部の更新かどうかを表す真偽値。真だとタイムスタンプが更新されない。
    • "keyword"
      • ページのキーワードを表す String を要素として持つ Array。指定されていなければ、現在のページのキーワードが指定される。
    • "title"
      • ページのタイトルを表す String。
    • "freeze"
      • ページを凍結するかを表す真偽値。管理者としてログインし、真を指定するとページを凍結する。そうでない場合は凍結を解除する。
戻り値

ページの編集に成功すれば true を返す。

例外
  • XMLRPC::FaultException (10: can't edit this page.)
    • ページを編集できないと発生する。
  • XMLRPC::FaultException (11: save failed.)
    • ページの保存に失敗すると発生する。

wiki.getAllPages -> Array

すべてのページ名の配列を返す。

戻り値

ページ名を表す String を要素として持つ Array を返す。

文字列の取り扱い

Hiki の XML-RPC インターフェースで扱う文字列のエンコーディングはすべて UTF-8 である。

XML-RPC を発行する際の引数として文字列を渡す場合は、単にエンコーディングが Encoding::UTF_8 である文字列を渡せばよい。

戻り値の文字列（配列やハッシュに含まれるものを含む）については注意が必要。バイト列としては確かに UTF-8 だが、String#encode は Encoding::ASCII-8BIT になっている（「Rubyist Magazine - 標準添付ライブラリ紹介 【第 1 回】 XMLRPC4R#XML-RPC で使える値の型」に記述されていることが原因？）。したがって、戻り値の文字列を使う前に String#force_encoding('UTF-8') を呼び出して、エンコーディングを一致させておくことが必要である。