[All]
QualityCentral Webサービスガイド
By: Tomohiro Takahashi
Abstract: QualityCentral(QC)のWebサービスインターフェースに関するドキュメントです。
これは、QualityCentral(QC)のWebサービスを利用するためのドキュメントです。
クライアント向けのWebサービスインターフェースに関するドキュメントはこちらです。このWebサービスは後方互換性を保ちつつ進化しており、新しいクライアントを実装する際にはアップデートがないかどうか確認するようにしてください。
Webサービスを使用する
上述したインターフェースのドキュメントを参照すると、多くのメソッドがBase64Binary型を返すことが分かると思います。それらのメソッドの戻り値は、XML形式のClientDatasetデータパケットを圧縮したものです。XML形式のClientDatasetデータパケットについて詳しく知りたい場合は、「The Express Way to the Internet, Part 2」の記事を参照してください。
DelphiやC++Builder、またはKylixで作成するアプリケーションでは、ClientDatasetコンポーネントのXMLDataプロパティに対して、圧縮されずエンコードもされていない形式の結果セットを直接割り当てることができます。
Session ID
QCにおけるほとんどのメソッドは、パラメータにセッションIDを必要とします。QCに登録済みのEmailアドレス／パスワードを使ってloginメソッドを呼び出すことにより、セッションIDを取得することができます。実際にはSessionIDは、userid、sysop level、email等（※password以外はoptionsダイアログで変更可能）を含む単一のユーザーレコードのカラムとして返されます。このデータパケットからセッションIDの値を取り出す必要があります。
このセッションIDは、Zlibによって圧縮された形式で返されます。以下で紹介しているDelphiコードは、SessionIDを処理するための「圧縮およびエンコード」用のルーチンを提供しています。いったんセッションIDを取り出してしまえば、それを必要とするすべてのメソッドにプレーンテキストの文字列として渡すことができます。現在、セッションIDは90分間有効です。90分以内に再度メソッドコールを行えば、セッションIDは引き続き90分間利用可能になります。
セッションIDの期限が切れた場合は、SOAP fault が返されます。この場合、その例外をトラップし、再びログインすることにより新しいセッションIDを取得することができます。
SOAP Fault
まだ実装されていないメソッドは、その旨を示す「SOAP fault」を返します。
説明が必要なメソッド
ほとんどのメソッドの名前には、分かり易い名前が付けられています。QC向けWebサービスクライアントを作成する際に最も重要なメソッドは、LastInterfaceChange です。これは、Webサービスインターフェースが最後に変更された日時を返します。既存のメソッドに新たにパラメータが追加されることもありますし、新たなメソッドが追加されることもあります。現在のインターフェースとの互換性が無くなってしまう変更が必要になることは滅多にありません。ただしまだベータ段階ですので、いくつかのメソッドに互換性が無くなる可能性はあります。
もしご自分でクライアントを作成しているのであれば、CurrentClientVersionメソッドはおそらく上述したメソッドよりも重要ではないでしょう。現在のGUIクライアントのバーションを返すものです。
GetOutlineは、すべてのプロジェクトの「アウトライン領域」を返します。これは内部的なものに関連するデータセットです。アクティブなプロジェクトに基づいて、この「アウトライン」をフィルタリングする必要があります。
GetProjectsは、すべてのプロジェクトのリストを返します。
利用可能なソースコード
以下のソースコードやルーチンは、QualityCentralのWebサービス向けにご自分でクライアントを作成する際に役立つものです。
Delphi
Java
これは、現時点で利用可能なJava向けのコードの抜粋です。
import java.io.*;
import java.util.zip.InflaterInputStream;
import javax.mail.internet.MimeUtility;
InputStream in = new InflaterInputStream( MimeUtility.decode(
new ByteArrayInputStream( bytes ), "base64" ) );
クライアントを記述する
クライアントを作成する際には、まずログインし、ほとんどのWebサービスメソッドを使用するためにセッションIDを取得する必要があります。上述したSessionIDに関する注意事項を参照してください。
テスト用のユーザーを使用する
テスト用のユーザーおよびテスト領域を作成してありますので、QCにある余計なデータを省くのに役立ちます。テストで報告を作成したり編集するには、このテスト用のユーザーを使用してください。次の情報を使えばテスト用のユーザーとしてログインできます。
Email: test@borland.com
Password: test
クライアントをテストする目的であれば、”Test project” 領域を使用してください。この領域のデータは定期的に削除されます。だいたい72時間ほどはアクティブなままにしておきますが、このテスト領域にどれだけデータが貯まっているかに依存します。
GetLookupを呼び出すための引数
ここでは、ルックアップテーブルに渡す単語の値について説明しています。このリストに関するアップデートがある場合には、ここを再度チェックしてみてください。
値 |
説明 |
Project |
公開されているプロジェクトのリスト。このカラムから得られるIDを、プロジェクトを必要とするものすべてに渡してください。 |
Platform |
すべてのプラットホームのリスト。プロジェクトカラムがNULLの場合はすべてのプロジェクトに属していることを示します。一方、プロジェクトのレコードから得られるIDは、それがそのプロジェクトに属していることを示しています。ID は、プラットホームを問い合わせた場合に保持されます。 |
Version |
すべてのバージョンのリスト。Projectカラムは、製品のどのバージョンなのかを示しています。Lookup_value が保持されています。 |
Type |
すべてのタイプ。Lookup_value が保持されています。 |
Severity |
重大性をルックアップするためのリスト。Lookup_value が保持されています。 |
Status |
ステータスのリスト。ID が保持されています。 |
Resolution |
すべての解決のリスト。ID が保持されています。 |
|
|
その他の注意事項
ルックアップ名に空文字列を渡すと、すべてのルックアップデータを取得できます（この手法は現在のクライアントでは動作し、それらはクライアント側のClientDatasetにプログラムで割り当てられます）。
lookup_name／projectの組み合わせ用に返されるソートIDはユニークなもので、ツリービューのソート順を変更します。多くのメソッドに渡される「lastDays」引数は、最近の何日間（NumberOfDays）のうちに作成または変更された項目のために使用します。
GetAttachmentでは、ファイル名を改行コード（CR,LF）で区切ることで、ファイルのリストを指定できます。現在はまだワイルドカードは利用できず、ファイル名を指定しなればなりません。すべてのファイルを取得したい場合には単に空文字列を渡してください。
ユーザー情報は、セッションIDを取得する際のログインプロセスの一部として返されます。これは、GetUserInformationのスーパーセットです。GetUserInfoは、他のユーザーに関する公開情報を取得するために使用します。
GUIクライアントでは、この機能はシスオペのレベルだけで利用でき、シスオペではないユーザーが行えない内容を隠したり（たとえ試みたとしても、サービス側ではそのセッションIDがシスオペに属しているかを常にチェックしています）、user_idに基づいて編集や削除を行えないようにしています。もしuser_idのようなものを参照したとしても（他の誰も自分のuser_idを知る必要は無いので、GetUserInformationで返されることはありません）、サービス側に戻されることは決してありません。ユーザーIDは常に、Loginメソッドから返されるセッションIDによって決定されます。
Connect with Us