複数の予定を取得する

目次

複数の予定を取得する

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

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

URL

クラウド版

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

パッケージ版

環境に合わせてそれぞれ以下を置き換えてください。

  • IP_ADDRESS_OR_HOST_NAME:Garoonのインストール先のIPアドレスまたはホスト名
  • INSTALL_IDENTIFER:Garoonのインストール識別子
Windows環境
http://IP_ADDRESS_OR_HOST_NAME/scripts/INSTALL_IDENTIFER/grn.exe/api/v1/schedule/events
Linux環境
http://IP_ADDRESS_OR_HOST_NAME/cgi-bin/INSTALL_IDENTIFER/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
次のいずれかの値を指定します。
  • GaroonユーザーID:出席者(ユーザー)によって絞り込む場合
  • 組織ID:出席者(組織)によって絞り込む場合
  • 施設ID:施設別に絞り込む場合
targetTypeを指定した場合は必須です。
targettargetTypeのどちらも省略した場合、次のいずれかの値を指定します。
  • target: APIを実行するユーザーのGaroonユーザー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);