google-tasks

Google Tasks を curl + jq で操作します。ユーザーの OAuth ベアラートークンは $GOOGLE_TASKS_TOKEN に格納されています。すべての呼び出しで、次の形式で指定する必要があります。 Authorization: Bearer $GOOGLE_TASKS_TOKEN。トークンには最低限、tasks.readonly と ID 関連のスコープ（openid email profile）が含まれます。インストール時にユーザーが書き込みを許可している場合は、より広い tasks スコープ（読み取りと書き込み）も含まれます。

Tasks API は標準的な JSON を返します。エラーは {"error": {"code": 401|403|..., "message": "..."}} の形式で返されるため、この エラーをそのまま表示してください。401 はトークンの期限切れを意味します（再インストールが必要です）。書き込み時の 403 insufficientPermissions は、ユーザーが tasks.readonly しか許可していないことを意味します。読み取りと書き込みの両方のチェックボックスをオンにして再インストールするよう、ユーザーに依頼してください。

必ず最初に users/@me/lists を呼び出して、そのアカウントにあるタスクリストを確認してください。デフォルトのリストに加え、calendar.google.com または Tasks アプリでユーザーが作成したリストも含まれます。

タスクの一括作成、完了、一括削除の前に、対象のタイトルを正確にユーザーに伝え、確認を求めてください。推測した ID を使ってタスクを削除しないでください。

レシピ

認証を確認して、すべてのタスクリストを一覧表示する（必ず最初に実行）

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq '.items[] | {id, title, updated}'

デフォルトのリストのタイトルは通常「我的任务」／「My Tasks」ですが、その後のすべての lists/{id}/tasks 呼び出しで必要なのは id（MTAxMjM0NTY3OA のような長い不透明な文字列）です。

すべてのリストから未完了のタスクをすべて一覧表示する

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode 'showCompleted=false' \
      --data-urlencode 'maxResults=100' \
      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, status, notes}'
  done | jq -s '. | sort_by(.due // "9999")'

showCompleted=false は、API 側で完了済みの項目を除外します。デフォルトの showCompleted=true&showHidden=false では、完了済みのタスクも返されます。

特定のリストの未完了タスクを期限順に並べる

LIST_ID='MTAxMjM0NTY3OA'
curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
  --data-urlencode 'showCompleted=false' \
  --data-urlencode 'maxResults=100' \
  | jq '.items // [] | sort_by(.due // "9999") | .[] | {title, due, notes, status, position}'

position は、リスト内でユーザーがドラッグして並べ替えた順序を表します。ユーザーが「タスクの一番上にあるのは何？」と聞いた場合に便利です。due フィールドがないタスクには期限がありません。

今日が期限のタスク

TODAY=$(date -u +%Y-%m-%d)
TOMORROW=$(date -u -d "+1 day" +%Y-%m-%d 2>/dev/null \
  || date -u -v+1d +%Y-%m-%d)
TODAY_START="${TODAY}T00:00:00.000Z"
TOMORROW_START="${TOMORROW}T00:00:00.000Z"

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode "dueMin=$TODAY_START" \
      --data-urlencode "dueMax=$TOMORROW_START" \
      --data-urlencode 'showCompleted=false' \
      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, notes}'
  done | jq -s

dueMin／dueMax は RFC 3339 形式のタイムスタンプです。Tasks API は due を UTC の午前0時として保存するため、日付の境界付近では現地日の範囲が概算になります。「今日が期限」という意味では問題ありません。ユーザーから指摘があった場合に限り、この点を説明してください。

期限を過ぎたタスク（期限が過去で、まだ未完了のものすべて）

NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode "dueMax=$NOW" \
      --data-urlencode 'showCompleted=false' \
      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, daysOverdue: (((now * 1000) - (.due | sub("Z"; "+00:00") | fromdateiso8601 * 1000)) / 86400000 | floor)}'
  done | jq -s

最近完了したタスク（今週分の振り返り）

ONE_WEEK_AGO=$(date -u -d "-7 days" +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null \
  || date -u -v-7d +%Y-%m-%dT%H:%M:%S.000Z)

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode 'showCompleted=true' \
      --data-urlencode 'showHidden=true' \
      --data-urlencode "completedMin=$ONE_WEEK_AGO" \
      | jq --arg list "$LIST_TITLE" '.items[]? | select(.status=="completed") | {list: $list, title, completed}'
  done | jq -s '. | sort_by(.completed)'

completedMin／completedMax は dueMin／Max と同じ形式で、すでに「完了」状態に移動されたタスクにのみ適用されます。該当するタスクを表示するには、showCompleted=true および showHidden=true を指定する必要があります。Google はデフォルトのリストでは完了済みのタスクを非表示にします。

1 件のタスクの詳細を取得する

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{title, due, status, notes, completed, position, links: .links}'

links には、ユーザーが手動で追加したハイパーリンク（メールや Drive ドキュメントなど）が含まれます。存在する場合は、リスト形式でユーザーに表示してください。

ページネーション

maxResults は 1 ページあたり最大 100 件です。nextPageToken を使用します。

LIST_ID='MTAxMjM0NTY3OA'
PAGE_TOKEN=''
while : ; do
  RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
    --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
    --data-urlencode 'maxResults=100' \
    --data-urlencode 'showCompleted=false' \
    ${PAGE_TOKEN:+--data-urlencode "pageToken=$PAGE_TOKEN"})
  echo "$RESP" | jq -c '.items[]?'
  PAGE_TOKEN=$(echo "$RESP" | jq -r '.nextPageToken // empty')
  [ -z "$PAGE_TOKEN" ] && break
done

書き込みレシピ

以下はすべて、より広い tasks スコープが必要です。ユーザーが tasks.readonly しか許可していない場合は、403 insufficientPermissions が返されます。その内容を伝え、読み取りと書き込みの両方のチェックボックスをオンにして再インストールするよう、ユーザーに依頼してください。

新しいタスクを追加する

LIST_ID='MTAxMjM0NTY3OA'
curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Draft Q2 plan","notes":"Outline + risks + asks.","due":"2026-05-15T00:00:00.000Z"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
  | jq '{id, title, due, status}'

Google は due を、指定した日の UTC 午前0時として保存します。UI では時刻は無視されます。リストの一番上に挿入するには、URL に ?previous=（値なし）を追加します。

ユーザーの確認を得てタスクを 3 件一括追加する

LIST_ID='MTAxMjM0NTY3OA'
DUE='2026-05-12T00:00:00.000Z'
for T in 'Reply to Alice' 'Review PR #404' 'Send meeting recap'; do
  curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data "{\"title\":$(jq -nr --arg t "$T" '$t'),\"due\":\"$DUE\"}" \
    "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
    | jq -c '{id, title, due}'
done

このループを実行する前に、作成するタイトルを必ず一覧表示し、ユーザーの承認を得てください。アトミックな一括処理用エンドポイントはありません。

タスクを完了済みにする

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"status\":\"completed\",\"completed\":\"$NOW\"}" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{id, title, status, completed}'

元に戻すには {"status":"needsAction","completed":null} を使用します。

タスクのタイトル／メモ／期限を編集する

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Draft Q2 plan (rev2)","notes":"Cover risks + asks + budget.","due":"2026-05-20T00:00:00.000Z"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{id, title, due, notes}'

タスクを削除する

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
curl -sS -X DELETE -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  -o /dev/null -w 'HTTP %{http_code}\n'

204 は成功を意味します。論理削除はありません。一度削除すると、タスクはなくなります。削除前にタイトルをユーザーに伝えてください。

並べ替え：タスクを指定した位置に移動する

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
PREV='dGFza0lkUHJldg'  # task id this one should appear AFTER; omit to move to top
curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  --data '' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID/move?previous=$PREV" \
  | jq '{id, title, parent, position}'

タスクを別のタスクの下にサブタスクとして入れ子にするには、?previous=... の代わりに ?parent=... を使用します。

新しいタスクリストを作成する

curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Q2 follow-ups"}' \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq '{id, title}'

一般的なエラーコード

HTTP	意味	ユーザーへの案内
401 UNAUTHENTICATED	トークンの有効期限切れ／失効	「Connections ページで Google Tasks コネクターを再接続してください。」
403 insufficientPermissions	書き込みスコープがありません	「この操作には Tasks の読み取り＋書き込みスコープが必要ですが、tasks.readonly しか許可されていません。読み取り＋書き込みのチェックボックスをオンにして、コネクターを再インストールしてください。」
404 notFound	リスト ID またはタスク ID が間違っています	users/@me/lists を使って再度一覧表示し、正しい ID を見つけてください。
429 quotaExceeded	クォータ超過／スロットリング	約 5 秒待ってから、1 回だけ再試行してください。

$GOOGLE_TASKS_TOKEN をログに記録したり、出力したりしないでください。秘密情報として扱ってください。