Developer's API Documentation : Tasks
同期 Syncing
多くのサードパーティ製アプリケーションの主たる目的は、タスクの同期をすることです。この勧めに従えば、きれいで効率的にタスクを同期することができます。最重要事項の一つとしては、「タスク最終更新」（"lastedit_task"）または「タスク最終削除」（"lastdelete_task"）のタイムスタンプを用いることです。これはアカウント情報（"Account Info"）から返されるもので、アプリケーションがサーバーから差分を取得・更新・削除する前に、サーバー上で変更があったかどうかを知ることができます。たいていの場合は、同期してもサーバー上に変更はなく、何もする必要がないので、タイムスタンプを用いることによって処理量・時間を大きく削減することができます。
図（本家サイトより拝借・加工。問題がある場合はご連絡ください）
アプリケーションとToodledoとの同期においては、以下の7つのシナリオを扱えなければなりません。
アプリケーションへのタスク追加
アプリケーションでのタスク更新
アプリケーションからのタスク削除
Toodledoサーバへのタスク追加
Toodledoサーバでのタスク更新
Toodledoサーバからのタスク削除
アプリケーションとサーバ双方でタスクが変更されている
シナリオ1, 2, 3では、アプリケーションはタスクを追加・更新・削除するために、それぞれ /tasks/add.php, /tasks/edit.php, /tasks/delete.php のAPIを用いることになります。追加と削除の場合は事前チェックの必要はありませんが、更新をする前には差分を取得し、修正日の比較をすることにより、タスクのより新しい更新を上書きしてしまわないようにしなければなりません。
シナリオ4, 5, 6では、アプリケーションはそれぞれ /tasks/get.php または /tasks/get_deleted.php のAPIを用いることになります。シナリオ7では、アプリケーションは修正日を比較し、双方で更新されているのかどうかを判断した後、ユーザーにどちらの版を残すかを尋ねます。すべてのシナリオは上のフローチャートに従うことで効率よく処理することができます。
タスクの属性
タスクにはいろいろ設定・取得できる項目があります。それらの属性の詳細を説明します。
id このタスクのサーバーID番号です。アカウントごとに一意であることが保証されていますが、アカウントが違えば同じID番号で違った内容のタスクになります。
title タスクの名前を表す文字列です。255文字まで。設定する際、& は %26 に、; は %3B にそれぞれエンコードしてください。
tag タスクにつけるタグです。コンマ , で区切られた文字列リストです。64文字まで。設定する際、& は %26 に、; は %3B にそれぞれエンコードしてください。
folder フォルダのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。
context コンテクストのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。
goal ゴールのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。
location ロケーションのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。
parent プロアカウント項目です。サブタスクへのアクセスに用いられます。サブタスクを作成するには、ここに親タスクの番号を設定します。デフォルトは0で、この場合は普通のタスクが作成されます。
children プロアカウント項目です。サブタスクへのアクセスに用いられます。このタスクが持っている子タスクの数を示します。サブタスクや、普通のタスクでは0となります。
order プロアカウント項目です。サブタスクへのアクセスに用いられます。これはintegerで、親タスク内での当該サブタスクの順番を示します。現在、これは読み取り専用としています。
duedate タスクの期限日についての、GMT unixのタイムスタンプです。このタイムスタンプのうち、時間の部分は関係ありません。サーバーから取得した際には、つねに正午に設定されます。
duedatemod due date modifier がどれなのか示すintegerです。
0：この日までに（Due by）
1：この日に（Due On：＝）
2：この日以降に（Due After）
3：オプション的（？）
startdate タスクの開始日についての、GMT unixのタイムスタンプです。このタイムスタンプのうち、時間の部分はつねに正午に設定されます。
duetime タスクの期限時間についての、GMT unixのタイムスタンプです。期限時間が設定されていなければ、0となります。期限日が設定されていないのに期限時間が設定されている場合、このタイムスタンプの日付 は1970年1月1日に設定されます。時間はfloating timesで記録されます。言い換えれば、10amとして設定されたものはそのタイムゾーンにおける10amです。このタイムスタンプをGMTの文字列に変換し、タイムゾーンに関わらず表示することもできます。
starttime タスクの開始時間についての、GMT unixのタイムスタンプです。開始時間が設定されていなければ、0となります。開始日が設定されていないのに開始時間が設定されている場合、このタイムスタンプの日付 は1970年1月1日に設定されます。時間はfloating timesで記録されます。言い換えれば、10amとして設定されたものはそのタイムゾーンにおける10amです。このタイムスタンプをGMTの文字列に変換し、タイムゾーンに関わらず表示することもできます。
remind duedateやduetimeのリマインダを送るまでの時間（分）をあらわすintegerです。リマインダがなければ0を設定します。設定値はリストに示される有効な数値に限られます（0, 1, 15, 30, 45, 60, 90, 120, 180, 240, 1440, 2880, 4320, 5760, 7200, 8640, 10080, 20160, 43200）。プロアカウントでなければ、0か60に限られます。無効な数値を入力すると、0でない近傍の数値に修正されます。
repeat タスクをどのように繰り返すかを示す文字列です。"Every 1 Week" や "On the 2nd Friday" です。詳しくはrepeat format faq を参照してください。タスクがリスケジュールされた際は、新しい日付に移行します。記録を残すためには、タスクの完全なコピーをユーザーのリストに加えるようにしてください。ここの場合は、新しいタスクには別のID番号が与えられ、終了状態となります。繰り返しを解除するには、空の文字列を設定してください。
repeatfrom どのようにタスクが繰り返されるのかを示します。0であれば期限日を基準とし、1であれば終了日を基準として繰り返します。
status タスクの状態を示すintegerです。
0：None なし
1：New Action 新しいアクション
2：Active アクティブ
3：Planning 計画中
4：Delegated 委託中
5：Waiting 待機
6：Hold 保留
7：Postponed 延期
8：Someday いつか
9：Canceled 中止
10：Reference 照会
length 終了までにかかる予想時間（分）を表すintegerです。
priority 優先度を表すintegerです。
-1：Negative 消極的
0：Low 低
1：Medium 中
2：High 高
3：Top 緊急
star タスクにスターがついているかどうかのboolean（0または1）です。
modified タスクが最後に修正された際のGMT UNIXタイムスタンプです。
completed タスクが終了した際のGMT UNIXタイムスタンプです。終了していなければ0です。Toodledoでは終了時刻は追っていないので、終了時刻は常に正午となります。
added タスクが追加された際のGMT UNIXタイムスタンプです。Toodledoでは追加時刻は追っていないので、追加時刻は常に正午となります。
timer タイマーにおいて、現在のセッションを含まずに、経過した時間（秒）を示す値です。 The value in the timer field indicates the number of seconds that have elapsed for the timer not including the current session.
timeron タイマーが起動している場合、ここにはタイマーが起動した最後の時間を示すUNIXタイムスタンプが保存されます。したがって、タイマーがまさに稼働中の場合、ユーザーには経過時間との差（timer欄）を計算して表示する必要があります。計算式は、Total Time=timer+(now-timeron) です。ただし、nowは現在日時のUNIXタイムスタンプです。
note 32000バイトまでのtext stringです。設定する際、& は %26 に、; は %3B にそれぞれエンコードしてください。
meta 255バイトまでのtext stringです。タスクのメタデータを保持します。Toodledoに適切な項目がないデータを同期するのに便利です。このデータはタスクIDごとに一意です。このデータはあなたのアプリケーションIDごとのプライベートなものです。ユーザーも他のアプリケーションIDも、あなたのアプリケーションがここに記述したデータを見ることはできません。実行の詳細により、meta項目を使用することでそれぞれのAPIを呼び出すのに余計に時間がかかることになります。したがって、必要なときのみ利用するようにしてください。 Because of an implementation detail, using the meta field introduces extra latency to each API call, so you should only use this field when necessary.
タスクの取得
タスクの追加
POSTにより tasks/add.php APIを呼び出すことにより、一度に50件までのタスクを追加することができます。titleは必須項目です。
必須項目
title
オプション
folder, context, goal, location, priority, status, star, duration, remind, starttime, duetime, completed, duedatemod, repeat, repeatFrom, tag, duedate, startdate, note, parent, meta
（言及なし）
id, children, order, length, modified, added, timer, timeron
ref という特別な項目があります。これは英数字のID番号で、これを通すことによって同期後にモノを一致させるのを補助する目的で用いられます。There is also a special field called "ref" that you can use to pass through an alphanumeric id number to aid in matching things up after a sync.
タスクは、以下のようなJSONオブジェクトを生成し、POSTによってAPIに送信することで追加されます。改行文字は \n としてください。データは適切にURLで送信できるようにエンコードしてください（%XXという文字列は+という文字にエンコードされます：symbols replaced with their %XX equivalent and spaces encoded as +）。各行のそれぞれの要素がひとつのタスクオブジェクトとなります。効率のために、単に設定したい項目だけを送信してください。
http://api.toodledo.com/2/tasks/add.php?key=YourKey;
アクションが成功すると、追加されたタスクは追加された順に返されます。個々のタスクに何らかのエラーが生じた場合は、返されたタスクの内部にアウトプットされるので、どのアクションが失敗したのかを特定することができます。
JSON:
URLに "f=xml" を付加することによって、APIが返す際のフォーマットをxmlに指定することもできます。
http://api.toodledo.com/2/tasks/add.php?key=YourKey;
XML:
タスクの更新
タスクの削除
削除されたタスクの取得
エラーコード一覧
最終更新：2012年06月11日 01:10
