Calendar API

Calendar API を利用して、予定の取得・作成・編集・削除やカレンダーの管理が可能です。

User Account 認証または Service Account 認証 (JWT) で取得した Access Token で利用できます。

Scopes: calendar, calendar.read

カレンダーの種類 {#calendar-type}

カレンダーには、ユーザーが持つ「マイカレンダー」、トークルームや組織/グループトークルームが持つ「トークルームカレンダー」、そして、すべてのユーザーが参照できる「会社カレンダー」があります。

マイカレンダーのうち、ユーザーごとに既定で作成されるカレンダーを「基本カレンダー」 、その他にユーザーが作成したカレンダーを「共有カレンダー」と呼びます。 マイカレンダーは他のユーザーと共有することができます。

参考: LINE WORKS ヘルプセンター > カレンダータイプ

Calendar API では マイカレンダー (基本カレンダー/共有カレンダー) と トークルームカレンダー へアクセスできます。

注意

• 会社カレンダーへは API によるアクセスはできません。

カレンダーの管理 {#manage-calendar}

ユーザーの基本カレンダーの情報は、以下の API で取得します。

ユーザーがアクセス可能なマイカレンダーおよびトークルームカレンダーのリストは、以下の API で取得できます。

共有カレンダーは、以下の API で作成できます。

カレンダー名や権限などの管理は、以下の API で行います。

ユーザーごとの、ブラウザやモバイルアプリでのカレンダーリストへの表示・非表示や表示順を切り替えることができます。

予定の管理 {#manage-event}

カレンダーの予定は、以下の API で管理します。これらの API を使用する場合には、calendarId を指定する必要があります。 calendarId は前述の各取得 API にて取得します。

基本カレンダー は、以下の API で予定を管理することもできます。これらの API は、calendarId を指定せずに使用します。

予定 {#event}

予定は、eventComponents オブジェクトとして指定または取得できます。
以下は、eventComponents オブジェクトの例です。

{    "eventComponents": [        {            "eventId": "EventID1234567890abcdefghijk",            "summary": "イベントの例",            "start": {                "dateTime": "2023-05-14T08:00:00",                "timeZone": "Asia/Tokyo"            },            "end": {                "dateTime": "2023-05-14T09:00:00",                "timeZone": "Asia/Tokyo"            },            "description" : "これはテストのイベントです。",            "location" : "中央会議室",            "transparency": "OPAQUE"        }    ]}

この例では、予定の件名 summary、終日でない予定の開始日時 dateTime と終了日時 dateTime、それぞれの timeZone、メモ description と場所 location、空き時間か予定ありかを示す transparency を含みます。
予定を登録する際には、eventId を指定する場合には、他のイベントと重複しない値でなければなりません。eventId を指定せずに予定を登録した場合には、システムにより、一意の eventId が割り当てられます。

参加者と設備 {#attendees-and-resource}

予定の主催者は主催者 organizer で、参加者は参加者リスト attendees で指定します。
どちらもメールアドレス email は必須で、表示名 displayName は任意で指定します。

{    "eventComponents": [        {            "eventId": "EventID1234567890abcdefghijk",            "summary": "イベントの例",            "start": {                "dateTime": "2023-05-14T08:00:00",                "timeZone": "Asia/Tokyo"            },            "end": {                "dateTime": "2023-05-14T09:00:00",                "timeZone": "Asia/Tokyo"            },            "description" : "これはテストのイベントです。",            "location" : "中央会議室",            "organizer": {                "email" : "organizer@example.com",                "displayName" : "会議の主催者"            },            "attendees" : [                {                    "email" : "attendee@example.com",                    "displayName" : "会議の参加者",                    "partstat" : "ACCEPTED",                    "isOptional" : true                }            ]        }    ]}

設備は、設備フラグ isResource を true とし、設備 ID id とリソースの固有値 resourceValue を指定します。
設備 ID id とリソースの固有値 resourceValue は、設備に対して一意の値が割り当てられています。API を利用して任意のリソースの設備 ID id とリソースの固有値 resourceValue を取得することはできませんが、設備を予約した予定を取得して、リソースの設備 ID id とリソースの固有値 resourceValue を取得できます。

...    "attendees": [        {            "id": "12345678/12345678@97d9ddb4-ae93-4469-8471-123456781234",            "resourceValue": "https://calendar.worksmobile.com/resources/resource/12345678/12345678@97d9ddb4-ae93-4469-8471-123456781234",            "isResource": true        }    ]...

繰り返しの予定 {#recurring-event}

eventComponents オブジェクトは、同じ eventId を持つ、一つまたは複数の Event オブジェクトを含みます。
eventComponents オブジェクトが一つの Event オブジェクトを含む場合、その予定は、単発の予定か、例外の無い繰り返しの予定です。繰り返し情報は recurrence 配列で示され、 recurrence 配列がない場合には、単発の予定です。
eventComponents オブジェクトが複数の Event を含む場合には、例外のある繰り返しの予定です。

以下は、例外を含む eventComponents オブジェクトの例です。

{    "eventComponents": [        {            "eventId": "EventID1234567890abcdefg",            "summary": "繰り返しイベントの例",            "start": {                "dateTime": "2023-05-24T08:00:00",                "timeZone": "Asia/Tokyo"            },            "end": {                "dateTime": "2023-05-24T09:00:00",                "timeZone": "Asia/Tokyo"            },            "recurrence": [                "RRULE:FREQ=DAILY;UNTIL=20230525T230000Z;INTERVAL=1",                "EXDATE;TZID=Asia/Tokyo:20230525T080000"            ]        },        {            "eventId": "EventID1234567890abcdefg",            "summary": "例外イベント",            "start": {                "dateTime": "2023-05-25T08:30:00",                "timeZone": "Asia/Tokyo"            },            "end": {                "dateTime": "2023-05-25T09:30:00",                "timeZone": "Asia/Tokyo"            },            "recurringEventId": "TZID=Asia/Tokyo:20230525T080000"        }    ]}

最初の Event オブジェクトでは、東京時間で 2023-05-24T08:00:00 から 2023-05-24T09:00:00 の予定 繰り返しイベントの例 を表しています。recurrence プロパティがあることから、繰り返しのイベントであることがわかります。
繰り返し情報は RRULE で示されます。この例では、INTEREVAL が 1 で FREQ が DAILY、つまり毎日繰り返して 20230525T230000Zに終了することを示していす。20230525T230000Z は UTC ですので、東京時間では 1 月 26 日 8 時に開始されるイベントが最後であることを意味します。
また、EXDATE は、繰り返しの例外となる予定の識別情報 TZID=Asia/Tokyo:20230525T080000 を示します。

2 つ目の Event オブジェクトは、例外となる予定の内容が確認できます。
recurringEventId は、親となる繰り返しイベントの recurrence オブジェクトに含まれる EXDATE の値 TZID=Asia/Tokyo:20230525T080000 と一致します。
summary (件名) が 例外イベント に、開始・終了時刻も当初の予定から変更されていることが確認できます。