Tasks APIの編集履歴ソース - toodledoapi @ ウィキ

Tasks API - (2012/06/11 (月) 00:36:15) のソース

*Developer's API Documentation : Tasks
http://api.toodledo.com/2/tasks/index.php
**同期　Syncing
多くのサードパーティ製アプリケーションの主たる目的は、タスクの同期をすることです。この勧めに従えば、きれいで効率的にタスクを同期することができます。最重要事項の一つとしては、「タスク最終更新」（"lastedit_task"）または「タスク最終削除」（"lastdelete_task"）のタイムスタンプを用いることです。これはアカウント情報（"Account Info"）から返されるもので、アプリケーションがサーバーから差分を取得・更新・削除する前に、サーバー上で変更があったかどうかを知ることができます。たいていの場合は、同期してもサーバー上に変更はなく、何もする必要がないので、タイムスタンプを用いることによって処理量・時間を大きく削減することができます。

図（本家サイトより拝借・加工。問題がある場合はご連絡ください）
#ref(SyncFlowTasksJp.png)

アプリケーションと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では、アプリケーションは修正日を比較し、双方で更新されているのかどうかを判断した後、ユーザーにどちらの版を残すかを尋ねます。すべてのシナリオは上のフローチャートに従うことで効率よく処理することができます。

**タスクの属性
タスクにはいろいろ設定・取得できる項目があります。それらの属性の詳細を説明します。
|&bold(){id}|このタスクのサーバーID番号です。アカウントごとに一意であることが保証されていますが、アカウントが違えば同じID番号で違った内容のタスクになります。|
|&bold(){title}|タスクの名前を表す文字列です。255文字まで。設定する際、& は %26 に、; は %3B にそれぞれエンコードしてください。|
|&bold(){tag}|タスクにつけるタグです。コンマ , で区切られた文字列リストです。64文字まで。設定する際、& は %26 に、; は %3B にそれぞれエンコードしてください。|
|&bold(){folder}|フォルダのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。|
|&bold(){context}|コンテクストのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。|
|&bold(){goal}|ゴールのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。|
|&bold(){location}|ロケーションのID番号です。フォルダに登録しない場合はこの項目自体を書き漏らしておくか、0を設定してください。|
|&bold(){parent}|プロアカウント項目です。サブタスクへのアクセスに用いられます。サブタスクを作成するには、ここに親タスクの番号を設定します。デフォルトは0で、この場合は普通のタスクが作成されます。|
|&bold(){children}|プロアカウント項目です。サブタスクへのアクセスに用いられます。このタスクが持っている子タスクの数を示します。サブタスクや、普通のタスクでは0となります。|
|&bold(){order}|プロアカウント項目です。サブタスクへのアクセスに用いられます。これはintegerで、親タスク内での当該サブタスクの順番を示します。現在、これは読み取り専用としています。|
|&bold(){duedate}|タスクの期限日についての、GMT unixのタイムスタンプです。このタイムスタンプのうち、時間の部分は関係ありません。サーバーから取得した際には、つねに正午に設定されます。|
|&bold(){duedatemod}|[[due date modifier]]がどれなのか示すintegerです。|
|~|0：この日までに（Due by）|
|~|1：この日に（Due On：＝）|
|~|2：この日以降に（Due After）|
|~|3：オプション的（？）|
|&bold(){startdate}|タスクの開始日についての、GMT unixのタイムスタンプです。このタイムスタンプのうち、時間の部分はつねに正午に設定されます。|
|&bold(){duetime}|タスクの期限時間についての、GMT unixのタイムスタンプです。期限時間が設定されていなければ、0となります。期限日が設定されていないのに期限時間が設定されている場合、&u(){このタイムスタンプの日付}は1970年1月1日に設定されます。時間はfloating timesで記録されます。言い換えれば、10amとして設定されたものはそのタイムゾーンにおける10amです。このタイムスタンプをGMTの文字列に変換し、タイムゾーンに関わらず表示することもできます。|
|&bold(){starttime}|タスクの開始時間についての、GMT unixのタイムスタンプです。開始時間が設定されていなければ、0となります。開始日が設定されていないのに開始時間が設定されている場合、&u(){このタイムスタンプの日付}は1970年1月1日に設定されます。時間はfloating timesで記録されます。言い換えれば、10amとして設定されたものはそのタイムゾーンにおける10amです。このタイムスタンプをGMTの文字列に変換し、タイムゾーンに関わらず表示することもできます。|
|&bold(){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でない近傍の数値に修正されます。|
|&bold(){repeat}|タスクをどのように繰り返すかを示す文字列です。"Every 1 Week" や "On the 2nd Friday" です。詳しくは[[repeat format faq]]を参照してください。タスクがリスケジュールされた際は、新しい日付に移行します。記録を残すためには、タスクの完全なコピーをユーザーのリストに加えるようにしてください。ここの場合は、新しいタスクには別のID番号が与えられ、終了状態となります。繰り返しを解除するには、空の文字列を設定してください。|
|&bold(){repeatfrom}|どのようにタスクが繰り返されるのかを示します。0であれば期限日を基準とし、1であれば終了日を基準として繰り返します。|
|&bold(){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　照会|
|&bold(){length}|終了までにかかる予想時間（分）を表すintegerです。|
|&bold(){priority}|優先度を表すintegerです。|
|~|-1：Negative　消極的|
|~|0：Low　低|
|~|1：Medium　中|
|~|2：High　高|
|~|3：Top　緊急|
|&bold(){star}|タスクにスターがついているかどうかのboolean（0または1）です。|
|&bold(){modified}|タスクが最後に修正された際のGMT UNIXタイムスタンプです。|
|&bold(){completed}|タスクが終了した際のGMT UNIXタイムスタンプです。終了していなければ0です。Toodledoでは終了時刻は追っていないので、終了時刻は常に正午となります。|
|&bold(){added}|タスクが追加された際のGMT UNIXタイムスタンプです。Toodledoでは追加時刻は追っていないので、追加時刻は常に正午となります。|
|&bold(){timer}|タイマーにおいて、現在のセッションを含まずに、経過した時間（秒）を示す値です。　The value in the timer field indicates the number of seconds that have elapsed for the timer not including the current session.|
|&bold(){timeron}|タイマーが起動している場合、ここにはタイマーが起動した最後の時間を示すUNIXタイムスタンプが保存されます。したがって、タイマーがまさに稼働中の場合、ユーザーには経過時間との差（timer欄）を計算して表示する必要があります。計算式は、Total Time=timer+(now-timeron) です。ただし、nowは現在日時のUNIXタイムスタンプです。|
|&bold(){note}|32000バイトまでのtext stringです。設定する際、& は %26 に、; は %3B にそれぞれエンコードしてください。|
|&bold(){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.
ref はタスクには保存されず、このコールにてエコーバックされるだけです。The "ref" field is not saved into the task, it is only echoed back to you on this call.

タスクは、以下のようなJSONオブジェクトを生成し、POSTによってAPIに送信することで追加されます。改行文字は \n としてください。データは適切にURLで送信できるようにエンコードしてください（%XXという文字列は+という文字にエンコードされます：symbols replaced with their %XX equivalent and spaces encoded as +）。各行のそれぞれの要素がひとつのタスクオブジェクトとなります。効率のために、単に設定したい項目だけを送信してください。

#blockquote(){#html2(){{{{{{
http://api.toodledo.com/2/tasks/add.php?key=YourKey;
tasks=[{"title"%3A"My Task"}%2C{"title"%3A"Another"%2C"star"%3A"1"%2C"ref"%3A"98765"}];
fields=folder,star

}}}}}}}

#blockquote(){
JSON: 
[{"id":"1234","title":"My Task","modified":1281990824,"completed":0,"folder":"0","star":"0"},
{"id":"1235","title":"Another","modified":1280877483,"completed":0,"folder":"0","star":"1","ref":"98765"}]
}


#blockquote(){
http://api.toodledo.com/2/tasks/add.php?key=YourKey;
tasks=[{"title"%3A"My Task"}%2C{"title"%3A"Another"%2C"star"%3A"1"%2C"ref"%3A"98765"}];
fields=folder,star;f=xml
}


#blockquote(){
XML: 
<tasks>
	<task>
		<id>1234</id>
		<title>My Task</title>
		<folder>0</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>0</star>
	</task>
	<task>
		<id>1235</id>
		<title>Another</title>
		<folder>0</folder>
		<modified>1234567890</modified>
		<completed></completed>
		<star>1</star>
		<ref>98765</ref>
	</task>
</tasks>
}
toodledoapi @ ウィキ

Tasks API

メニュー

リンク

他のサービス

Tasks API - (2012/06/11 (月) 00:36:15) のソース
