LINE WORKS のカレンダー API で他の人に予定を投げ込む

LINE WORKS v2.7 でカレンダー API が新しくなりました。
変更ポイントを紹介しつつ、実際に使ってみたいと思います。

#カレンダー API の種類
現在、カレンダー API は大きく２つあります。
##これまで (~v2.6) のカレンダー API
LINE WORKS の API には大きくサーバー API / サービス API の 2 種類があります。

|API の種類|特徴|
|:-----------------|------------------:|:------------------:|
|サーバー API| システム権限で動作する API、ユーザーログイン不要|
|サービス API| 各ユーザーの権限で動作する API、利用時に Web UI でユーザーログインが必要|

これまで、カレンダー API はサービス API のみが提供されていました。
そのため、利用者自身の権限で、自分のカレンダーを操作することだけが可能でした。

##これから (v2.7~)のカレンダー API
v2.7 のアップデートにあわせて、新たに、移行時のデータコピーなどに使えるサーバー API が追加されました。
ただし、現時点では提供機能が一部に限られています。

### カレンダー サーバー API で提供される機能
- カレンダーの作成/削除
- 予定の作成/変更/削除

### カレンダー サーバー API で提供されない主な機能
- カレンダー情報の照会 / 修正
- カレンダーリストの照会
- カレンダー内の予定リストの照会
- 予定詳細の照会

このように「新規にカレンダーを作って放り込む」使い方はできるけれど「今ある情報を参照する」使い方は引き続きサービス API 限定となります。

#カレンダー API を使ってみる
新しくなった API を使って、さっそくカレンダーを登録して予定を追加してみます。
下記は Python3.8.0 を利用しています。

##カレンダーの作成

API の説明はこちら。[カレンダーの作成](https://developers.worksmobile.com/jp/document/100702701?lang=ja)


```python:calendarlist.py

import json
import requests
import urllib.parse

APIID="Developer Console で取得した API ID"
SERVER_CKEY = "Developer Console で取得した Server Consumer Key"
SERVER_TOKEN = "サーバー認証トークン"

def CalendarlistS(ServerTOKEN,AccountId,**CalParams):
    #リクエストURLの作成
    apiurl =  'https://apis.worksmobile.com/r/'+ APIID + 'calendarList/'+ urllib.parse.quote(AccountId) + '/calendarList'
    
    header = {
        'consumerKey': SERVER_CKEY,
        'Authorization': 'Bearer ' + SERVER_TOKEN,
        'Content-Type': 'application/json'
    }
    #CalParamsをカレンダーの設定値として渡す
    r = requests.post(apiurl, headers = header, json = CalParams)
    return r

#作成例
cal=CalendarlistS(SERVER_TOKEN,'demo@exampletenant',name='demo calendar',description='hogehoge')

#作成したカレンダー ID は returnValue に入る
Cal_ID = cal.json()['returnValue']

```
他の API ではメンバー指定に externalKey という値を使うものも多いのですが、カレンダー API の accountId は ID@domain 形式なので注意してください。

##カレンダーに予定の追加
続いて、作成したカレンダーに予定を登録します。

```python:calendarlist.py
def CalendareventS(ServerTOKEN,AccountId,CalendarId,**EventParams):
    #リクエストURLの作成
    apiurl =  'https://apis.worksmobile.com/r/'+ APIID + '/calendar/v1/' + urllib.parse.quote(AccountId) + '/calendars/'+CalendarId+'/events'
    
    header = {
        'consumerKey': SERVER_CKEY,
        'Authorization': 'Bearer ' + ServerTOKEN,
        'Content-Type': 'application/json'
    }
    #EventParamsを予定情報として渡す
    r = requests.post(apiurl, headers = header, json = EventParams)
        return r
```

予定のパラメータは ical 形式で指定します。書き方は[こちら](https://developers.worksmobile.com/jp/document/1007011)を参考にします。

```demo.ics
BEGIN:VCALENDAR
VERSION:2.0
PRODID:NO Calendar
CALSCALE:GREGORIAN
BEGIN:VTIMEZONE
TZID:Asia/Tokyo
BEGIN:STANDARD
DTSTART:19700101T000000
TZNAME:GMT+09:00
TZOFFSETFROM:+0900
TZOFFSETTO:+0900
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
SEQUENCE:0
CLASS:PUBLIC
TRANSP:OPAQUE
UID:demodemodemo-001-001
DTSTART;TZID=Asia/Tokyo:20191212T150000
DTEND;TZID=Asia/Tokyo:20191212T160000
SUMMARY:サンプル予定
DESCRIPTION:詳細 説明
LOCATION:東京オフィス
ORGANIZER;CN=山田太郎:mailto:taro@example.com
ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;CN=出席者:mailto:user01@example.com
CREATED:20191212T015408Z
LAST-MODIFIED:20191212T015408Z
DTSTAMP:20191212T015409Z
END:VEVENT
END:VCALENDAR
```

予定の登録は、1つずつ行う必要があります。カレンダーアプリからエクスポートした ics ファイルは複数の予定(VEVENT)が含まれていると思いますが、そのままインポートしようとするとエラーになるので気をつけてください。
最初に作ったカレンダーに予定を登録するのはこんな形です。

```python:
f=open('demo.ics')
eventdata=f.read()
f.close()
event=CalendareventS(SERVER_TOKEN,'demo@exampletenant',Cal_ID,ical=eventdata)
```
個人の基本カレンダーに登録できない、参照がないため一方向だけ、という課題はありますが、他のシステムからの予定の流し込みや便利に使えそうですね。