Jul 19, 2007

Trac の XML-RPC API にチャレンジ

Trac XML-RPC Plugin
http://trac-hacks.org/wiki/XmlRpcPlugin
root/xmlrpcplugin/0.10/tracrpc/api.py
http://trac-hacks.org/browser/xmlrpcplugin/0.10/tracrpc/api.py

Trac 0.10.3 の XML-RPC API

Trac XML-RPC Plugin を導入すると、http://example.com/mytrac/xmlrpc (Trac のトップ画面の URL に /xmlrpc を付加する)で API を閲覧することができる。 Trac 0.10.3 に 0.10 用の XML-RPC Plugin を導入した環境では下記の API が使用できる。


wiki
Function Description Permission required
struct wiki.getRecentChanges(dateTime.iso8601 since) Get list of changed pages since timestamp WIKI_VIEW
int wiki.getRPCVersionSupported() Returns 2 with this version of the Trac API. WIKI_VIEW
string wiki.getPage(string pagename, int version=None) Get the raw Wiki text of page, latest version. WIKI_VIEW
string wiki.getPageVersion(string pagename, int version=None) Get the raw Wiki text of page, latest version. WIKI_VIEW
string wiki.getPageHTML(string pagename, int version=None) Return page in rendered HTML, latest version. WIKI_VIEW
string wiki.getPageHTMLVersion(string pagename, int version=None) Return page in rendered HTML, latest version. WIKI_VIEW
array wiki.getAllPages() Returns a list of all pages. The result is an array of utf8 pagenames. WIKI_VIEW
struct wiki.getPageInfo(string pagename, int version=None) Returns information about the given page. WIKI_VIEW
struct wiki.getPageInfoVersion(string pagename, int version=None) Returns information about the given page. WIKI_VIEW
boolean wiki.putPage(string pagename, string content, struct attributes) writes the content of the page. WIKI_CREATE
array wiki.listAttachments(string pagename) Lists attachments on a given page. WIKI_VIEW
base64 wiki.getAttachment(string path) returns the content of an attachment. WIKI_VIEW
boolean wiki.putAttachment(string path, base64 data) (over)writes an attachment. Returns True if successful.This method is compatible with WikiRPC. putAttachmentEx has a more extensive set of (Trac-specific) features. WIKI_MODIFY
boolean wiki.putAttachmentEx(string pagename, string filename, string description, base64 data, boolean replace=True) Attach a file to a Wiki page. Returns the (possibly transformed) filename of the attachment. Use this method if you don't care about WikiRPC compatibility. WIKI_MODIFY
boolean wiki.deleteAttachment(string path) Delete an attachment. WIKI_DELETE
array wiki.listLinks(string pagename) Not implemented WIKI_VIEW
string wiki.wikiToHtml(string text) Render arbitrary Wiki text as HTML. WIKI_VIEW

search - Search Trac.
Function Description Permission required
array search.getSearchFilters() Retrieve a list of search filters with each element in the form (name, description). SEARCH_VIEW
array search.performSearch(string query, array filters=[]) Perform a search using the given filters. Defaults to all if not provided. Results are returned as a list of tuples in the form (href, title, date, author, excerpt). SEARCH_VIEW

ticket.milestone - Interface to ticket milestone objects.
Function Description Permission required
array ticket.milestone.getAll() Get a list of all ticket milestone names. TICKET_VIEW
struct ticket.milestone.get(string name) Get a ticket milestone. TICKET_VIEW
int ticket.milestone.delete(string name) Delete a ticket milestone TICKET_ADMIN
int ticket.milestone.create(string name, struct attributes) Create a new ticket milestone with the given attributes. TICKET_ADMIN
int ticket.milestone.update(string name, struct attributes) Update ticket milestone with the given attributes. TICKET_ADMIN

ticket.severity - Interface to ticket severity.
Function Description Permission required
array ticket.severity.getAll() Get a list of all ticket severity names. TICKET_VIEW
string ticket.severity.get(string name) Get a ticket severity. TICKET_VIEW
int ticket.severity.delete(string name) Delete a ticket severity TICKET_ADMIN
int ticket.severity.create(string name, string value) Create a new ticket severity with the given value. TICKET_ADMIN
int ticket.severity.update(string name, string value) Update ticket severity with the given value. TICKET_ADMIN

ticket.type - Interface to ticket type.
Function Description Permission required
array ticket.type.getAll() Get a list of all ticket type names. TICKET_VIEW
string ticket.type.get(string name) Get a ticket type. TICKET_VIEW
int ticket.type.delete(string name) Delete a ticket type TICKET_ADMIN
int ticket.type.create(string name, string value) Create a new ticket type with the given value. TICKET_ADMIN
int ticket.type.update(string name, string value) Update ticket type with the given value. TICKET_ADMIN

system - Core of the XML-RPC system.
Function Description Permission required
array system.multicall(array signatures) Takes an array of XML-RPC calls encoded as structs of the form (in a Pythonish notation here): {'methodName': string, 'params': array} XML_RPC
array system.listMethods() This method returns a list of strings, one for each (non-system) method supported by the XML-RPC server. XML_RPC
string system.methodHelp(string method) This method takes one parameter, the name of a method implemented by the XML-RPC server. It returns a documentation string describing the use of that method. If no such string is available, an empty string is returned. The documentation string may contain HTML markup. XML_RPC
array system.methodSignature(string method) This method takes one parameter, the name of a method implemented by the XML-RPC server. It returns an array of possible signatures for this method. A signature is an array of types. The first of these types is the return type of the method, the rest are parameters. XML_RPC
array system.getAPIVersion() Returns a list with two elements. First element is the major version number, second is the minor. Changes to the major version indicate API breaking changes, while minor version changes are simple additions, bug fixes, etc. XML_RPC

ticket.resolution - Interface to ticket resolution.
Function Description Permission required
array ticket.resolution.getAll() Get a list of all ticket resolution names. TICKET_VIEW
string ticket.resolution.get(string name) Get a ticket resolution. TICKET_VIEW
int ticket.resolution.delete(string name) Delete a ticket resolution TICKET_ADMIN
int ticket.resolution.create(string name, string value) Create a new ticket resolution with the given value. TICKET_ADMIN
int ticket.resolution.update(string name, string value) Update ticket resolution with the given value. TICKET_ADMIN

ticket.priority - Interface to ticket priority.
Function Description Permission required
array ticket.priority.getAll() Get a list of all ticket priority names. TICKET_VIEW
string ticket.priority.get(string name) Get a ticket priority. TICKET_VIEW
int ticket.priority.delete(string name) Delete a ticket priority TICKET_ADMIN
int ticket.priority.create(string name, string value) Create a new ticket priority with the given value. TICKET_ADMIN
int ticket.priority.update(string name, string value) Update ticket priority with the given value. TICKET_ADMIN

ticket.component - Interface to ticket component objects.
Function Description Permission required
array ticket.component.getAll() Get a list of all ticket component names. TICKET_VIEW
struct ticket.component.get(string name) Get a ticket component. TICKET_VIEW
int ticket.component.delete(string name) Delete a ticket component TICKET_ADMIN
int ticket.component.create(string name, struct attributes) Create a new ticket component with the given attributes. TICKET_ADMIN
int ticket.component.update(string name, struct attributes) Update ticket component with the given attributes. TICKET_ADMIN

ticket.version - Interface to ticket version objects.
Function Description Permission required
array ticket.version.getAll() Get a list of all ticket version names. TICKET_VIEW
struct ticket.version.get(string name) Get a ticket version. TICKET_VIEW
int ticket.version.delete(string name) Delete a ticket version TICKET_ADMIN
int ticket.version.create(string name, struct attributes) Create a new ticket version with the given attributes. TICKET_ADMIN
int ticket.version.update(string name, struct attributes) Update ticket version with the given attributes. TICKET_ADMIN

ticket - An interface to Trac's ticketing system.
Function Description Permission required
array ticket.query(string qstr="status!=closed") Perform a ticket query, returning a list of ticket ID's. TICKET_VIEW
array ticket.getRecentChanges(dateTime.iso8601 since) Returns a list of IDs of tickets that have changed since timestamp. TICKET_VIEW
array ticket.getAvailableActions(int id) Returns the actions that can be performed on the ticket. TICKET_VIEW
array ticket.get(int id) Fetch a ticket. Returns [id, time_created, time_changed, attributes]. TICKET_VIEW
int ticket.create(string summary, string description, struct attributes={}, boolean notify=False) Create a new ticket, returning the ticket ID. TICKET_CREATE
array ticket.update(int id, string comment, struct attributes={}, boolean notify=False) Update a ticket, returning the new ticket in the same form as getTicket(). TICKET_APPEND
int ticket.delete(int id) Delete ticket with the given id. TICKET_ADMIN
struct ticket.changeLog(int id, int when=0) Return the changelog as a list of tuples of the form (time, author, field, oldvalue, newvalue, permanent). While the other tuple elements are quite self-explanatory, the permanent flag is used to distinguish collateral changes that are not yet immutable (like attachments, currently). TICKET_VIEW
array ticket.listAttachments(int ticket) Lists attachments for a given ticket. Returns (filename, description, size, time, author) for each attachment. TICKET_VIEW
base64 ticket.getAttachment(int ticket, string filename) returns the content of an attachment. TICKET_VIEW
string ticket.putAttachment(int ticket, string filename, string description, base64 data, boolean replace=True) Add an attachment, optionally (and defaulting to) overwriting an existing one. Returns filename. TICKET_APPEND
boolean ticket.deleteAttachment(int ticket, string filename) Delete an attachment. TICKET_ADMIN
array ticket.getTicketFields() Return a list of all ticket fields fields. TICKET_VIEW

ticket.status - Interface to ticket status.
Function Description Permission required
array ticket.status.getAll() Get a list of all ticket status names. TICKET_VIEW
string ticket.status.get(string name) Get a ticket status. TICKET_VIEW
int ticket.status.delete(string name) Delete a ticket status TICKET_ADMIN
int ticket.status.create(string name, string value) Create a new ticket status with the given value. TICKET_ADMIN
int ticket.status.update(string name, string value) Update ticket status with the given value. TICKET_ADMIN

Java から Trac XML-RPC API にアクセスしてみる

試しに Java から Trac 上の Ticket を取得してみた。 ライブラリをインストールするのが面倒だったので、自前で HTTP コネクションを張っている。

サンプルコード

public void testTracApi() throws Exception {

  URL url = new URL("http://example.com/trac/xmlrpc");
  HttpURLConnection con = (HttpURLConnection) url.openConnection();
  con.setDoOutput(true);
  con.setDoInput(true);
  con.setRequestMethod("POST");
  con.addRequestProperty("content-type", "text/xml");
  OutputStream os = null;

  try {
    os = con.getOutputStream();
    String request = 
      "<methodCall>\n" + 
      "  <methodName>ticket.get</methodName>\n" +
      "  <params>" + 
      "  <param><value><int>3</int></value></param>" + 
      "  </params>" + 
      "</methodCall>\n";
    os.write(request.getBytes());
  } finally {
    if (os != null) {
      os.close();
    }
  }

  ByteArrayOutputStream baos = new ByteArrayOutputStream();
  InputStream is = null;
  try {
    is = con.getInputStream();
    int ch = 0;
    while ((ch = is.read()) >= 0) {
      baos.write(ch);
    }
  } finally {
    if (is != null) {
      is.close();
    }
  }

  System.out.println("" + baos.toString("UTF-8"));
}

レスポンス

<?xml version='1.0'?>
<methodResponse>
<params>
<param>
<value><array><data>
<value><int>3</int></value>
<value><int>1179403566</int></value>
<value><int>1179403566</int></value>
<value><struct>
<member>
<name>status</name>
<value><string>new</string></value>
</member>
<member>
<name>description</name>
<value><string>基本的な設定を行う。</string></value>
</member>
<member>
<name>reporter</name>
<value><string>et</string></value>
</member>
<member>
<name>cc</name>
<value><string></string></value>
</member>
<member>
<name>resolution</name>
<value><string></string></value>
</member>
<member>
<name>component</name>
<value><string>Continuum</string></value>
</member>
<member>
<name>summary</name>
<value><string>Continuum 設定</string></value>
</member>
<member>
<name>priority</name>
<value><string>major</string></value>
</member>
<member>
<name>keywords</name>
<value><string></string></value>
</member>
<member>
<name>version</name>
<value><string></string></value>
</member>
<member>
<name>milestone</name>
<value><string>[Continuum] M1</string></value>
</member>
<member>
<name>owner</name>
<value><string>me</string></value>
</member>
<member>
<name>type</name>
<value><string>task</string></value>
</member>
</struct></value>
</data></array></value>
</param>
</params>
</methodResponse>

TrackBack ping me at
http://www.in-vitro.jp/blog/index.cgi/Trac/20070719_01.trackback
Post a comment

writeback message: Ready to post a comment.