複数の予定を取得する

目次

複数の予定を取得する

クエリで条件を指定して、複数の予定を取得します。

  • 繰り返し予定を含む場合は、すべての日の予定が返ります。
  • 仮予定を含む場合は、すべての候補の予定が返ります。
  • クエリで target を指定しない場合は、API を実行したユーザーが参加する予定だけを取得します。
  • 画面で「予定あり」と表示されていても、API を実行したユーザーが閲覧できない予定(非公開の予定)は取得できません。
    非公開の予定を含む予定の有無を調べる場合は、 空き予定を検索する API を利用してください。

URL

クラウド版

https://sample.cybozu.com/g/api/v1/schedule/events

パッケージ版
Windows 環境
http://サーバーのIPアドレスまたはホスト名/scripts/インストール識別子/grn.exe/api/v1/schedule/events
Linux 環境
http://サーバーのIPアドレスまたはホスト名/cgi-bin/インストール識別子/grn.cgi/api/v1/schedule/events

HTTP メソッド

GET

利用できるバージョン

  • クラウド版 Garoon
  • パッケージ版 Garoon 4.10 以降

必要なアクセス権

  • 予定の閲覧権限

リクエスト

パラメーター

リクエストパラメーターは、URL クエリパラメーターとして送信してください。
ただし、 Garoon REST API リクエストを送信する API を使って実行する場合は、リクエストボディとして指定できます。

パラメーター名 必須 説明
fields 文字列 省略可 取得するプロパティ
スケジュールオブジェクト のプロパティを指定できます。
複数のプロパティを指定するには、半角カンマで区切ります。
orderBy 文字列 省略可 ソート条件
プロパティ名と並び順の間に半角スペースを入れて指定します。
たとえば、createdAt を降順で並べ替える場合には、「orderBy=createdAt desc」を指定します。
指定できるプロパティ名および並び順は次のとおりです。
  • プロパティ名
    • createdAt
    • updatedAt
    • start
  • 並び順
    • asc
    • desc
省略すると、updatedAt の昇順で並べ替えられます。
rangeStart 文字列 省略可 予定の開始日時の取得期間(開始日時)
rangeStart で指定した日時より後に開始する予定に絞り込みます。
RFC 3339 形式で指定します。
たとえば、日本時間の2022年10月19日9時10分30秒を指定したい場合には、次のように指定します。
  • UTC で指定する場合:「2022-10-19T00:10:30Z」
  • JST で指定する場合:「2022-10-19T09:10:30+09:00」
rangeEnd を指定する場合には、rangeEnd より前の値を指定してください。
rangeEnd 文字列 省略可 予定の終了日時の取得期間(終了日時)
rangeEnd で指定した日時より前に終了した予定に絞り込みます。
RFC 3339 形式で指定します。
rangeStart を指定する場合には、rangeStart より後の値を指定してください。
target 文字列 条件必須 絞り込みに使用する ID
次のいずれかの値を指定します。
  • ユーザー ID:出席者(ユーザー)によって絞り込む場合
  • 組織 ID:出席者(組織)によって絞り込む場合
  • 施設 ID:施設別に絞り込む場合
targetType を指定した場合は必須です。
targettargetType のどちらも省略した場合、次のいずれかの値を指定します。
  • target: API を実行するユーザーのユーザー ID
  • targetType:「user」
targetType 文字列 条件必須 絞り込みに使用する ID のタイプ
次のいずれかの値を指定します。
  • user:出席者(ユーザー)を絞り込む場合
  • organization:出席者(組織)を絞り込む場合
  • facility:施設を絞り込む場合
target を指定した場合は必須です。
keyword 文字列 条件必須 予定検索のキーワード
次のいずれかの項目にキーワードを含む予定に絞り込みます。
  • タイトル
  • 会社情報
  • メモ
  • コメント
excludeFromSearch を指定した場合は必須です。
excludeFromSearch 文字列 省略可 キーワード検索から除外する項目
次のいずれかの値を指定します。
  • subject:タイトル
  • company:会社情報
  • notes:メモ
  • comments:コメント
複数の項目を指定するには、半角カンマで区切ります。
showPrivate 真偽値 省略可 次にいずれかに該当する、閲覧権限のない予定も含めて取得するかどうかを指定します。
取得できるスケジュールオブジェクトのプロパティには制限があります。詳細は、 閲覧権限がない予定で取得できるプロパティ を参照してください。
  • API を実行するユーザーが参加していない、非公開の予定
  • スケジュールのアクセス権で閲覧権限が設定されていない予定
クラウド版 Garoon およびパッケージ版 Garoon 5.15 以降でのみ利用できるパラメーターです。
次のいずれかの値を指定します。
  • true:取得する
  • false:取得しない
省略した場合、false が設定されます。
非公開の予定を完全に隠す設定 (External link) をしている場合、targetType に「user」または「organization」を指定していると、非公開の予定を取得できません。
limit 数値 省略可 取得する予定の件数
1 から 1,000 まで指定できます。省略すると 100 が設定されます。
指定された条件に一致する予定がさらにある場合でも、指定した値より取得できる予定の数は少なくなる可能性があります。
リクエストパラメーターで指定された条件に一致するレコードの中で、閲覧権限がないレコードは除外されます。
offset 数値 省略可 取得する予定の先頭からスキップする数
省略すると、 0 が設定されます。
リクエストの例
URL

https://sample.cybozu.com/g/api/v1/schedule/events?limit=100&orderBy=updatedAt%20asc

ヘッダー
1
2
3
{
  "X-Cybozu-Authorization": "QWRtaW5pc3RyYXRvcjpjeWJvenU="
}

リクエストヘッダーの詳細は Garoon REST API の共通仕様 を参照してください。

ボディ
1
2
3
4
{
  "limit": 30,
  "orderBy": "updatedAt asc"
}

レスポンス

処理が成功すると、予定の内容が JSON 形式で返ります。
形式の詳細は スケジュールオブジェクト を確認してください。

レスポンスの例
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
{
  "events": [
    {
      "id": "123",
      "creator": {
        "id": "1",
        "code": "c000001",
        "name": "Noboru Satoh(Satoh Noboru); Sales Department"
      },
      "createdAt": "2017-09-26T06:25:18Z",
      "updater": {
        "id": "1",
        "code": "c000001",
        "name": "Noboru Satoh(Satoh Noboru); Sales Department"
      },
      "updatedAt": "2017-09-26T06:25:18Z",
      "eventType": "REGULAR",
      "eventMenu": "conference",
      "subject": "Weekly conference",
      "notes": "This is notes.\nYou can write multiple lines.",
      "visibilityType": "PUBLIC",
      "useAttendanceCheck": true,
      "companyInfo": {
        "name": "Cybozu, Inc.",
        "zipCode": "103-xxxx",
        "address": "2-7-1, Nihombashi, Chuo-ku, Tokyo",
        "route": "Nihombashi Sta. - Ginza Line - Shibuya Sta.",
        "routeTime": "18",
        "routeFare": "195",
        "phone": "03-4306-xxxx"
      },
      "attachments": [
        {
          "id": "1",
          "name": "figure.png",
          "contentType": "image/png",
          "size": "64251"
        }
      ],
      "start": {
        "dateTime": "2017-09-27T14:00:00+09:00",
        "timeZone": "Asia/Tokyo"
      },
      "end": {
        "dateTime": "2017-09-27T14:00:00+09:00",
        "timeZone": "Asia/Tokyo"
      },
      "isAllDay": "false",
      "isStartOnly": "false",
      "originalStartTimeZone": "Asia/Tokyo",
      "originalEndTimeZone": "Asia/Tokyo",
      "attendees": [
        {
          "id": "1",
          "code": "c000001",
          "name": "Noboru Satoh(Satoh Noboru); Sales Department",
          "type": "USER",
          "attendanceResponse": {
            "status": "PENDING",
            "comment": "I am going to attend the meeting."
          }
        }
      ],
      "watchers": [
        {
          "id": "1",
          "code": "c000001",
          "name": "Noboru Satoh(Satoh Noboru); Sales Department",
          "type": "USER"
        }
      ],
      "facilities": [
        {
          "id": "1",
          "name": "28F conference room",
          "code": "F001"
        }
      ],
      "facilityUsingPurpose": "Because of the explanation of a new plan.",
      "facilityReservationInfo": {
        "additionalProp1": {
          "type": "SINGLE_LINE_TEXT",
          "value": "Custom field value"
        },
        "additionalProp2": {
          "type": "SINGLE_LINE_TEXT",
          "value": "Custom field value"
        },
        "additionalProp3": {
          "type": "SINGLE_LINE_TEXT",
          "value": "Custom field value"
        }
      },
      "facilityUsageRequests": [
        {
          "status": "APPROVED",
          "facility": {
            "id": "1",
            "name": "28F conference room",
            "code": "F001"
          },
          "approvedBy": {
            "id": "1",
            "code": "c000001",
            "name": "Noboru Satoh(Satoh Noboru); Sales Department"
          },
          "approvedDateTime": "2017-09-26T06:25:18Z"
        }
      ],
      "repeatInfo": {
        "type": "EVERY_DAY",
        "period": {
          "start": "2017-04-01",
          "end": "2018-03-31"
        },
        "time": {
          "start": "09:00",
          "end": "18:00"
        },
        "timeZone": "Asia/Tokyo",
        "isAllDay": false,
        "isStartOnly": false,
        "dayOfWeek": "MON",
        "dayOfMonth": "EOM",
        "exclusiveDateTimes": [
          {
            "start": "2017-12-28T00:00:00+09:00",
            "end": "2017-12-29T00:00:00+09:00"
          }
        ]
      },
      "temporaryEventCandidates": [
        {
          "end": {
            "dateTime": "2017-06-06T09:00:00+09:00",
            "timeZone": "Asia/Tokyo"
          },
          "start": {
            "dateTime": "2017-06-06T10:00:00+09:00",
            "timeZone": "Asia/Tokyo"
          },
          "facility": {
            "id": "1",
            "code": "room-a",
            "name": "ROOM-A"
          }
        }
      ],
      "additionalItems": { // パッケージ版 Garoon 6.0 より前のバージョンでのみ利用できます
        "item": {
          "value": "string"
        }
      },
      "repeatId": "201712150900"
    }
  ],
  "hasNext": false
}

additionalItems は、パッケージ版 Garoon 6.0 より前のバージョンでのみ利用できます。
予定に関する付加情報を保存する場合は、カスタマイズ項目(Schedule Datastore)を利用してください。
詳細は、次のページを参照してください。
カスタム項目(additionalItems)の廃止について

サンプルコード

curlを使ったリクエスト
1
2
curl -X GET 'https://sample.cybozu.com/g/api/v1/schedule/events?limit=100&orderBy=updatedAt%20asc' \
  -H 'X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU='
Garoon REST API リクエストを送信する API を使ったリクエスト
1
2
3
4
5
6
const body = {
  limit: 100,
  orderBy: 'updatedAt asc'
};

await garoon.api('/api/v1/schedule/events', 'GET', body);