Scalix Platform API概要

出典: ScalixWikiJP

目次

[編集]

概要

Scalixメッセージングサービスは単純で強力なREST形式のウェブサービスAPIを提供します。 このAPIを使うとメールボックスのデータへのアクセスやメッセージ配送や空き時間情報や検索を行うことができ、一つの単純なプロトコルを使って容易に統合する機会を提供します。

ScalixメッセージングサービスはPlatform APIを使って次の機能を提供します。

  • Userinfo: ユーザ情報（本人のみ）の取得
  • Mailbox Access: メールボックスへのアクセス
  • Message Delivery: メッセージの送信
  • Free-Busy: ユーザの空き時間情報へのアクセス
  • Search: 検索

Platform APIはRESTであるため、次のような特徴を持っています。

  • RESTはリソース指向です。システムのどのアイテム（メッセージ、フォルダなど）でもそれに関連づけられたURLを持ちます。
  • アイテムのURLを与えられると、アイテムを取得、作成、修正、削除するためにそれぞれGET, POST, PUT, DELETEのような標準のHTTPリクエストを使うことができます。
  • 追加のパラメータはURLの一部を構成します。
  • いくつかの異なる形式でコンテンツを出力することができます。

APIのエントリポイントは http(s)://host:port/api です。

Platform APIについての文書は次のURLで見ることができます。 

http://host:port/api/docs

この文書は上記の文書の要約です。

[編集]

Scalix Direct Reference

Scalix Direct Referenceはメッセージストアにあるアイテム（フォルダやメッセージ）をユニークに識別する16文字の文字列です。メッセージストアは各アイテムが作成されたときにそのアイテムに対してdirect referenceを割り当てます。アイテムの内容が変更されても、アイテムが異なる場所に移動しても、（メッセージのIMAP UIDが変更しても）その文字列は不変です。

ScalixウェブサービスAPIにおいて、direct referenceは個別のメッセージを参照します。新規に作成されたアイテムでは、direct referenceの値は標準のLocationヘッダのそばにあるX-Scalix-Directrefヘッダの値として返されます。

[編集]

URL Schema

Scalixシステムの各リソースは個別に示すことができるように割り当てられたURLを持っています。リソースの例としては次のものがあります。

  • フォルダ
  • メッセージ
  • メッセージのパート (MIMEパート)

例外が少しありますが、ScalixメッセージングサービスのURLは一般的に次の構造に従います。 

http(s)://host:port/api/ foo@example.com /mailbox /INBOX/00026728e90b589f ?output=xml
            1                   2            3               4                 5

URLのそれぞれの位置の下にある番号は次の定義に従います。

  1. APIエンドポイント: サービスのエンドポイント。
  2. 主に使うメールアドレス: 内容にアクセスする人のメールアドレス。
  3. サービス: サービス名
  4. リソース: アイテムへのパス（サービスによっては無い場合がある）
  5. クエリオプション: 追加のオプション
[編集]

サービス

APIが提供するサービスには以下のものがあります。

  • userinfo
  • mailbox
  • search
  • delivery
  • freebusy
[編集]

userinfo

ログインしているユーザの次の情報を取得します。

  • smtpaddress: メールアドレス
  • displayname: 表示名
  • userclass: ユーザクラス(Full or Limited)
  • mailbox: mailboxサービスへパス (例: '/foo@example.org/mailbox')

次のURLの形式でアクセスできます。 

http(s)://host:port/api/userinfo

Platform APIのサービスを利用する場合はまずこのURLにアクセスして認証を受けるのがよいでしょう。

[編集]

mailbox

mailboxサービスは次のメールボックスアイテムへのアクセスを提供します。

  • フォルダ一覧
  • フォルダ内の内容（メッセージ一覧）
  • メッセージ毎の情報
  • メッセージの各パート毎へのアクセス

典型的な使用例には次にものがあります。

  • RSS, ATOM, JSONなどの様々な形式でのメッセージ一覧
  • iCal (WebCal)でのカレンダデータの取得
  • メールボックスアイテムの生成および修正
  • 他の装置との同期

アクセス可能なアイテム

  1. フォルダ一覧
  2. フォルダ内のメッセージのSubject一覧
  3. メッセージの情報（主要なヘッダとボディパートのContent-Typeの情報）
  4. メッセージのボディパート（添付ファイルを含む）
  5. メッセージ（復号化していない状態）
  6. メッセージヘッダ（復号化していない状態）

HTTPメソッド

  • GET: メッセージアイテムの取得
  • POST: フォルダやメッセージの作成
    • メッセージの作成
    • カレンダアイテム(iCal)の作成
    • 連絡先アイテムの作成
    • フォルダの作成
  • PUT: 既存のメッセージの修正（カレンダと連絡先アイテムに限る）
  • DELETE: メッセージの削除

オプションのパラメータ

  • type: 出力するIPMの種類
  • flags: フラグによる絞り込み(現時点ではunreadのみサポート)
  • sort: ソートの種類(date, subject, from等)
  • sort-direction: ソートの順番(asc, desc(default))
  • start: 出力の開始番号
  • end: 出力の終了番号
[編集]

search

searchサービスはSearch and Index Service (SIS)のフロントエンドとして機能します。

次の形式のURLにアクセスすると検索を行うことができます。 

http(s)://host:port/api/<email-address>/search

searchの後に"/フォルダ名"を付けるとそのフォルダ内のメッセージのみを検索します。

オプションのパラメータ

  • q: 検索の条件式
  • flags: 検索条件のフラグによる絞り込み (flagged, unflagged, seen, unseen, answered, unanswered)
  • start: 結果の開始番号
  • end: 結果の終了番号

startとendは組み合わせて用います。

[編集]

検索の条件式

検索する単語の前に'from:', 'to:', 'subject:', 'body:'のどれかを付けることにより検索対象のメッセージの条件を絞り込みすることができます。 'AND'や'OR'で単語をスペースを挟んでつなげると論理積や論理和の条件を付加することができます。 

q=from:nick%20AND%20subject:scalix
[編集]

delivery

deliveryサービスはメールの送信を行います。

次のURLの形式でHTTP POSTのリクエストを送ります。 

http(s)://host:port/api/<email-address>/delivery

HTTPのリクエストのボディにはMIME形式のメッセージを格納します。

[編集]

freebusy

空き時間検索は次の二つのことを行うことができます。

  • 他の人（自身も含め）のスケジュールの空き時間の検索を行い、iCal形式のデータとして受け取る（HTTP GETを利用）
  • 自身の空き時間データを更新する（HTTP POSTを利用）

次のURLの形式でアクセスすることができます。 

http(s)://host:port/api/<email-address>/freebusy

<email-address>には検索したい人のメールアドレスで置き換えます。

オプションのパラメータ

  • dtstart: 検索対象の開始日時（UTCタイムスタンプ YYYYMMDDTHHMMSSZ の形式）
  • dtend: 検索対象の終了日時（UTCタイムスタンプ YYYYMMDDTHHMMSSZ の形式）

dtstartとdtendは組み合わせて用います。

[編集]

サポートしている出力フォーマット

mailboxとsearchサービスにおいてoutputクエリパラメータで指定することにより出力形式を指示することができます。

outputパラメータの指示がない場合には、（User-AgentヘッダやAcceptヘッダがある場合など）ウェブブラウザからのアクセスと思われる場合にはHTMLで出力し、そうでない場合にはXMLで出力します。

サポートしている出力フォーマットには次のものがあります。

  • xml: Scalix XML Schema
  • html: HTML
  • ical: カレンダ情報としてiCal形式
  • vcard: 連絡先情報としてVCARD形式
  • rss: RSSフィード
  • atom: ATOMフィード
  • json: JavaScript Object Notation
[編集]

ショートカット

mailboxサービスにおいていくつかのショートカットを提供しています。 このショートカットを使うことにより、読み取りのみではありますが、簡易に情報を取得することができます。

例えば、次のURLの形式でアクセスするとrssの情報を取得することができます。 

http(s)://host:port/api/<email-address>/rss
http(s)://host:port/api/<email-address>/rss/<folder-name>

ショートカットの種類

  • rss: mailboxサービスで出力形式を'rss'にした場合と同じ
  • atom: mailboxサービスで出力形式を'atom'にした場合と同じ
  • ical: mailboxサービスで出力形式を'ical'にした場合と同じ
[編集]

XML Schema

原文を参照してください。

[編集]

Custom HTTP Headers

Platform APIは次の標準ではないHTTPヘッダを使います。

  • X-Scalix-Flags
  • X-Scalix-UID
  • X-Scalix-Directref
[編集]

X-Scalix-Flags

このヘッダはmailboxサービスで(HTTP POSTやPUTで)メッセージにフラグを設定したり解除したりするために利用します。

フラグ一覧

  • DELETED: 削除済みフラグ
  • FLAGGED: フラグ
  • SEEN: 既読フラグ
  • ANSWERED: 返信済みフラグ
  • JUNK: ジャンクフラグ
  • NONJUNK: ノンジャンクフラグ
  • DRAFT: 草稿フラグ
  • FORWARDED: 転送済みフラグ
  • LABEL1 ... LABEL5: レーベル付きフラグ

複数のフラグを設定したり解除したりするためには接頭語として'+'や'-'をフラグ名に付け、各フラグ名はスペースで区切って並べます。 

例) X-Scalix-Flags: -SEEN +LABEL2
[編集]

X-Scalix-UID

HTTP POSTでメッセージを追加したり、PUTで既存のメッセージを修正したりするときにレスポンスヘッダはこの新しいメッセージのIMAP UIDを含めたヘッダを付けます。

[編集]

X-Scalix-Directref

HTTP POSTで新しいアイテムを追加したときに、レスポンスヘッダはこのアイテムに割り当てられた参照値を返します。

[編集]

Using Scalix Web Services

原文を参照してください。

"http://wiki.scalix.co.jp/wiki/index.php/Scalix_Platform_API%E6%A6%82%E8%A6%81" より作成