2016-05-26
EmacsからGoogle Calendar APIにアクセスする

org-modeでタスク管理をしているとGoogleカレンダーとの同期がしたくなりますよね。

現在はMobileOrg(Android版)のカレンダー登録機能を使っているのですが一定時間おきに同期するので予定がすぐ見られないことが良くありますし、AndroidのMobileOrg自体出来があまり良くなくて同期に失敗していつの間にか止まっていたりします。

org-modeのマニュアルではiCalendar(.ics)へエクスポートしてサーバに置いておく方法が紹介されていますがGoogleのボットが見に行くのに時間がかかるのであまり即時性はありません。

org-gcal.elを試したのですがエラーで動かないことやリクエストが終わらずそのまま何も起こらなかったりしてしまいました(予定はダウンロードできる(たまにできない)がアップは出来ない)。それと私がやりたかったのはagendaで出てくるような複数ファイル上の予定をそのままGoogleカレンダーへ設定したいだけだったので、わずかに使い方が異なるというのもありました。

動かない原因を探そうにも前提知識無しでorg-gcal.elをいきなり読んでもよく分かりません。

というわけで、勉強がてら色々参考にしながらEmacs LispでGoogle Calendar APIにアクセスするコードを書いてみました。

Google APIライブラリが整備されている他の言語や外部のツール(GoogleCL)を使うという手もあるのですがそこはとりあえずWindowsだから面倒ということで。

Google Developer Consoleで認証情報を作成

これから作るelisp(クライアントアプリ)がGoogleカレンダーにアクセスできるように、Google Developer Consoleで認証情報を作成する必要があります。

手順は次の通りです。

  1. Google Developer Consoleへアクセス
  2. プロジェクトの作成(プロジェクト名はCalendar Access From Emacsとでもした)
  3. 概要→Calendar API→有効にする→認証情報に進む
  4. プロジェクトへの認証情報の追加画面
    1. 必要な認証情報の種類を調べる
      • 必要な認証情報の種類「Google Calendar API」
      • APIを呼び出す場所「その他のUI(Windows、CLIツールなど)
      • アクセスするデータの種類「ユーザーデータ」
    2. OAuth 2.0 クライアントIDを作成する
      • 名前「gcal.el」
    3. OAuth 2.0 同意画面を設定する
      • メールアドレスとユーザーに表示するサービス名を適当に設定
    4. 完了
  5. 認証情報→クライアントの名前部分をクリック 必要な情報を確認
    • クライアントID (ex: 1234-xxxxxxxxx.apps.googleusercontent.com)
    • クライアントシークレット (ex: Xxx1xXxxXxx2xxXxxxXxx3xXxxx)

url-retrieve-synchronouslyでHTTPアクセス

request.elも魅力的なのですが今回はurl-retrieve-synchronouslyを使ってみます。

url-retrieve系は色々おかしな挙動を示すこともありますが基本的な使い方は簡単です。

クエリ文字列をPOSTしてレスポンス全体を文字列で受け取るには次のようにします。(Http Post – EmacsWikiより)

(require 'url)

(let ((url-request-method        "POST")
      (url-request-extra-headers `(("Content-Type" . "application/x-www-form-urlencoded")))
      (url-request-data          "field1=Hello&field2=from&field3=Emacs"))
  (with-current-buffer (url-retrieve-synchronously url)
    (buffer-string)))

また、今回はjsonの処理を多用します。jsonとlispオブジェクトとの変換は、Emacsに標準で入っているjson.elを使用します。

(require 'json)

(json-read-from-string "{\"name\": \"Taro\", \"age\": 18}")
 ;;=> ((name . "Taro") (age . 18))

(json-encode '((name . "Taro") (age . 18)))
 ;;=> "{\"name\":\"Taro\",\"age\":18}"

実際には文字列はutf-8でやりとりする必要があるので、encode-coding-stringやdecode-coding-stringで変換してやる必要があります。環境(標準のcoding system)によるのかもしれませんが私の所では送受信とも変換してやる必要がありました。

(json-read-from-string (decode-coding-string response-body 'utf-8))

(encode-coding-string (json-encode json-obj) 'utf-8)

これらを統合して、本プロジェクトでHTTPにアクセスするために使う関数をこしらえました。

主に使うのは gcal-retrieve-json- で始まる三つの関数です。

  • (gcal-retrieve-json-get url params)
  • (gcal-retrieve-json-post-www-form url params)
  • (gcal-retrieve-json-post-json url params obj)

これらは url にリクエストを出して返ってきたレスポンスをJSONとして解釈してその結果をlispオブジェクトで返します。

メソッドをGETにするかPOSTにするか、また、POSTにするなら何をPOSTするかで三つのバリエーションを用意しました。

関数の実装は次の通りです。

;; HTTP

(defun gcal-http (method url params headers data)
  (let ((url-request-method (or method "GET"))
        (url-request-extra-headers headers)
        (url-request-data data))
    (gcal-parse-http-response
     (url-retrieve-synchronously (gcal-http-make-query-url url params)))))

(defun gcal-parse-http-response (buffer)
  "バッファ内のHTTPレスポンスを解析して、ステータス、ヘッダー、ボディ等に分割します。"
  (with-current-buffer buffer
    ;; Response Line (ex: HTTP/1.1 200 OK)
    (beginning-of-buffer)
    (if (looking-at "^HTTP/[^ ]+ \\([0-9]+\\) ?\\(.*\\)$")
        (let ((status (string-to-number (match-string 1)))
              (message (match-string 2))
              (headers)
              (body))
          (next-line)
          ;; Header Lines
          (while (not (eolp))
            (if (looking-at "^\\([^:]+\\): \\(.*\\)$")
                (push (cons (match-string 1) (match-string 2)) headers))
            (next-line))

          ;; Body
          (next-line)
          (setq body (buffer-substring (point) (point-max)))

          ;; Result
          ;;(push (cons ":Body" body) headers)
          ;;(push (cons ":Status" status) headers)
          ;;(push (cons ":Message" message) headers)
          (list status message headers body)
          ))))

(defun gcal-http-get (url params)
  "指定されたurlへparamsをGETします。"
  (gcal-http "GET" url params nil nil))

(defun gcal-http-post-www-form (url params)
  "指定されたurlへparamsをPOSTします。"
  (gcal-http "POST" url nil
             '(("Content-Type" . "application/x-www-form-urlencoded"))
             (gcal-http-make-query params)))

(defun gcal-http-post-json (url params json-obj)
  "指定されたurlへjsonをPOSTします。"
  (gcal-http "POST" url params
             '(("Content-Type" . "application/json"))
             (encode-coding-string (json-encode json-obj) 'utf-8)))


(defun gcal-retrieve-json-get (url params)
  "指定されたurlへparamsをGETして得られるjsonを解析したリストを返します。"
  (gcal-http-response-to-json (gcal-http-get url params)))

(defun gcal-retrieve-json-post-www-form (url params)
  "指定されたurlへparamsをPOSTして得られるjsonを解析したリストを返します。"
  (gcal-http-response-to-json (gcal-http-post-www-form url params)))

(defun gcal-retrieve-json-post-json (url params json-obj)
  "指定されたurlへparamsとjsonをPOSTして得られるjsonを解析したリストを返します。"
  (gcal-http-response-to-json (gcal-http-post-json url params json-obj)))


(defun gcal-http-response-to-json (response)
  "レスポンス(gcal-http, gcal-parse-http-responseの戻り値)のボディをjson-read-from-stringします。"
  (let* ((status (nth 0 response))
         (body (nth 3 response)))
    ;;@todo check status
    (json-read-from-string (decode-coding-string body 'utf-8))))

(defun gcal-http-make-query (params)
  "クエリ文字列を作成します。(ex: a=1&b=2&c=3)"
  (url-build-query-string params))

(defun gcal-http-make-query-url (url params)
  "クエリ付きのURLを作成します。(ex:http://example.com/?a=1&b=2&c=3)"
  (let* ((query (gcal-http-make-query params)))
    (if (> (length query) 0) (concat url "?" query) url)))

OAuth 2.0で認証

カレンダーにアクセスするには認証が必要です。認証はOAuthで行います。

やることはだいたい次の通りです。

  1. 認証ページをWebブラウザで開いてユーザーに認証してもらい、認証ページに表示された認証コードをEmacsに入力してもらう。
  2. 認証コードからトークン情報(アクセストークン、失効までの時間、リフレッシュトークン)を取得する。
  3. 失効時間が来たらリフレッシュする(リフレッシュトークンを使って新しいアクセストークンと失効までの時間を取得する)。
  4. トークン情報を保存・復帰する。 (面倒なので今回はパス)
;;
;; OAuth
;; (この部分は一応Google Calendar以外でも使い回せるように作っています)
;;
;; Example: (setq token (gcal-oauth-get token "https://accounts.google.com/o/oauth2/auth" "https://www.googleapis.com/oauth2/v3/token" "xxx.apps.googleusercontent.com" "secret_xxx" "https://www.googleapis.com/auth/calendar"))

(defstruct gcal-oauth-token access expires refresh url)

(defun gcal-oauth-get (token auth-url token-url client-id client-secret scope)
  "アクセストークンを取得します。必要なら認証やリフレッシュを行います。"
  (if token
      (if (time-less-p (gcal-oauth-token-expires token) (current-time))
          (setq token (gcal-oauth-refresh token client-id client-secret token-url)))
    (setq token (gcal-oauth-auth auth-url token-url client-id client-secret scope)))

  token)

(defun gcal-oauth-auth (auth-url token-url client-id client-secret scope)
  "OAuthによりアクセストークンを取得します。gcal-oauth-token構造体を返します。"
  (let* ((result (gcal-oauth-get-access-token auth-url token-url client-id client-secret scope))
         (access-token (cdr (assq 'access_token result)))
         (expires-in (cdr (assq 'expires_in result)))
         (refresh-token (cdr (assq 'refresh_token result)))
         (expires (time-add (current-time) (seconds-to-time expires-in))))
    (make-gcal-oauth-token
     :access access-token
     :expires expires
     :refresh refresh-token
     :url token-url)))

(defun gcal-oauth-refresh (token client-id client-secret &optional token-url)
  "gcal-oauth-token構造体のアクセストークンをリフレッシュします。"
  (let* ((result (gcal-oauth-get-refresh-token
                  (gcal-oauth-token-refresh token)
                  (or token-url (gcal-oauth-token-url token))
                  client-id client-secret))
         (access-token (cdr (assq 'access_token result)))
         (expires-in (cdr (assq 'expires_in result)))
         (expires (time-add (current-time) (seconds-to-time expires-in))))
    (when (and access-token expires)
      (setf (gcal-oauth-token-access token) access-token)
      (setf (gcal-oauth-token-expires token) expires)))
  token)


   ;; implementation details
(defun gcal-oauth-get-access-token (auth-url token-url client-id client-secret scope)
  "アクセストークンを取得します。JSONをリストへ変換したもので返します。"
  (gcal-retrieve-json-post-www-form
   token-url
   `(
     ("client_id" ,client-id)
     ("client_secret" ,client-secret)
     ("redirect_uri" "urn:ietf:wg:oauth:2.0:oob")
     ("grant_type" "authorization_code")
     ("code" ,(gcal-oauth-get-authorization-code auth-url client-id scope)))))

(defun gcal-oauth-get-authorization-code (auth-url client-id scope)
  "ブラウザを開いてユーザに認証してもらい、認証コードを受け付けます。"
  (browse-url
   (concat auth-url
           "?client_id=" (url-hexify-string client-id)
           "&response_type=code"
           "&redirect_uri=" (url-hexify-string "urn:ietf:wg:oauth:2.0:oob")
           "&scope=" (url-hexify-string scope)))
  (read-string "Enter the code your browser displayed: "))

(defun gcal-oauth-get-refresh-token (refresh-token token-url client-id client-secret)
  "リフレッシュされたアクセストークンを取得します。JSONをリストへ変換したもので返します。"
  (gcal-retrieve-json-post-www-form
   gcal-token-url
   `(
     ("client_id" ,client-id)
     ("client_secret" ,client-secret)
     ("redirect_uri" "urn:ietf:wg:oauth:2.0:oob")
     ("grant_type" "refresh_token")
     ("refresh_token" ,refresh-token))))

Google Calendar APIを実際に使ってみる

認証

上で作成した関数を使用してGoogle Calendar API用の認証を行います。

(defcustom gcal-client-id "xxxxxxx.apps.googleusercontent.com" "client-id for Google Calendar API")
(defcustom gcal-client-secret "XxxClieNtSeCretXx" "client-secret for Google Calendar API")

(defconst gcal-auth-url "https://accounts.google.com/o/oauth2/auth")
(defconst gcal-token-url "https://www.googleapis.com/oauth2/v3/token")
(defconst gcal-scope-url "https://www.googleapis.com/auth/calendar")

(defvar gcal-access-token nil)

(defun gcal-access-token ()
  (setq gcal-access-token
        (gcal-oauth-get
         gcal-access-token
         gcal-auth-url gcal-token-url
         gcal-client-id gcal-client-secret gcal-scope-url))
  (gcal-oauth-token-access gcal-access-token))

gcal-client-idgcal-client-secret は最初にGoogle Developer Consoleで取得した情報を設定する必要があります。

(gcal-access-token)でアクセストークンが手に入ります。 初回はブラウザが開くので、そのページでアクセスを承認して認証コードを表示させ、そのコードをEmacsのミニバッファへ入力する必要があります。

カレンダー一覧

さて、実際にカレンダーの情報にアクセスしてみましょう。

まずは認証したアカウントが持つカレンダーの一覧を取得する方法。

(gcal-retrieve-json-get
 "https://www.googleapis.com/calendar/v3/users/me/calendarList"
 `(
   ("access_token" ,(gcal-access-token))
   ("key" ,gcal-client-secret)
   ("grant_type" "authorization_code")
   ))

次のような結果が返ってきます。

(
 (kind . "calendar#calendarList")
 (etag . "\"1234567890123456\"")
 (nextSyncToken . "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=")
 (items . [
           (
            (kind . "calendar#calendarListEntry")
            (etag . "\"1234567890123456\"")
            (id . "example@gmail.com")
            (summary . "example@gmail.com")
            (timeZone . "Asia/Tokyo")
            (colorId . "2")
            (backgroundColor . "#d06b64")
            (foregroundColor . "#000000")
            (selected . t)
            (accessRole . "owner")
            (defaultReminders . [((method . "popup") (minutes . 30)) ((method . "sms") (minutes . 30))])
            (notificationSettings (notifications . [((type . "eventCreation") (method . "email")) ((type . "eventChange") (method . "email")) ((type . "eventCancellation") (method . "email"))]))
            (primary . t)
           )
           (
            (kind . "calendar#calendarListEntry")
            (etag . "\"1234567890123456\"")
            (id . "ja.japanese#holiday@group.v.calendar.google.com")
            (summary . "日本の祝日")
            (description . "日本の祝日と行事")
            (timeZone . "Asia/Tokyo")
            (colorId . "7")
            (backgroundColor . "#42d692")
            (foregroundColor . "#000000")
            (selected . t)
            (accessRole . "reader")
            (defaultReminders . [])
           )
          ])
 )

追加で指定できるパラメータや得られる結果等についてはAPIリファレンス(CalendarList: list)を参照してください。

イベント(予定)のリスト

カレンダーID example@gmail.com のイベントを取得するには次のようにします。

(gcal-retrieve-json-get
 "https://www.googleapis.com/calendar/v3/calendars/example@gmail.com/events"
 `(
   ("access_token" ,(gcal-access-token))
   ("key" ,gcal-client-secret)
   ("grant_type" "authorization_code")
   ))

追加で指定できるパラメータや得られる結果等についてはAPIリファレンス(Events: list)を参照してください。

イベント(予定)の追加

(gcal-retrieve-json-post-json
 "https://www.googleapis.com/calendar/v3/calendars/example@gmail.com/events"
 `(
   ("access_token" ,(gcal-access-token))
   ("key" ,gcal-client-secret)
   ("grant_type" "authorization_code")
   )
 `(
   ("start"  ("date" "2016-05-25") )
   ("end"  ("date" "2016-05-26"))
   ("summary" "テストの予定2")
   )
 )

APIリファレンス(Events: lisert)

バッチ

多量のリクエストを送る(50まで)にはmultipartなHTTPリクエストを送るんだそうです。

url-retrieveはmultipartはできないみたいなのでrequest.elを使った方が良いかもしれません(?)

ソースはGitHubで

上のコードはgcal.elとして、また、org-modeのアクティブタイムスタンプをイベントとしてアップするコードをgcal-org.elとしてGitHub上に置きました。

https://github.com/misohena/gcal

Pingback / Trackback