mixi Connect » mixi Graph API » 技術仕様 » Calendar API
Calendar API
カレンダにはユーザ個人の過去の記録や未来の予定だけではなく、ユーザが誰とどのような時間を過ごしたか、過ごすかを書き留めておくことができます。そのような情報を手軽に、様々なシチュエーションで利用するためにCalendar APIは存在します。 ここでは、Calendar APIの使用方法について説明します。
事前に必要なもの
Calendar APIを利用するためには、以下の情報をすでに入手している必要があります。
- “r_calendar”または”w_calendar”スコープおよびその両方について認可されたアクセストークン
上記以外のスコープで認可されたアクセストークンを使用して、Calendar APIにアクセスすることはできません。アクセストークンの入手方法については、認証認可手順のページをご覧ください。
Calendar APIで提供される機能とスコープ
Calendar APIでは様々な機能が提供されますが、それらは大きく「参照系」「投稿系」の2つに分類されます。この分類は、そのままCalendar APIを利用するためのスコープに対応します。以下に、スコープと各機能の対応を示します
| スコープ | 機能 |
|---|---|
| r_calendar | 日程決定済みスケジュールの取得 |
| w_calendar | 日程決定済みスケジュールの投稿 |
スケジュールの取得（ID指定）
IDを指定してスケジュールを取得するためのURIは以下となります。
GET https://api.mixi-platform.com/2/calendar/schedules/[User-ID]/@self/[Schedule-ID]
| パラメータ名 | 指定する値 |
|---|---|
| User-ID | 認可ユーザのユーザID、および認可ユーザ自身を示す"@me"、または友人のユーザID。スケジュールの作成者を指定する。 |
| Schedule-ID | あるスケジュールのID。 |
さらに、以下のクエリパラメータをサポートしています。
| パラメータ名 | 説明 |
|---|---|
| fields | 取得したい情報の項目をカンマ区切りで指定します。 指定可能な項目名は「description,privacy,owner,owner.thumbnailUrl,owner.profileUrl, attendees,attendees.thumbnailUrl,attendees.profileUrl」です。もしfieldsパラメータを省略した場合には、「description,privacy,owner,owner.thumbnailUrl,owner.profileUrl, attendees,attendees.thumbnailUrl,attendees.profileUrl」が指定されたと見なされます。start_timeとtitleについては、必ず結果に含まれます。 またowner,attendeesを指定した場合はそれぞれowner.id,owner.displayNameとattendees.id,attendees.displayNameが必ず結果に含まれます。 |
正常に取得できた場合は、以下のような結果を得ることができます。
{
"entry":{
"id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"start_time":"2012-01-01T00:00:00+09:00",
"title":"お正月",
"description":"あけましておめでとうございます",
"privacy":{
"visibility":"public"
},
"owner":{
"id":"xxxxxxxxxxxxx",
"displayName":"表示名",
"thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
"profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
},
"attendees":[
{
"id":"xxxxxxxxxxxxx",
"displayName":"表示名",
"thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
"profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
},
..以下略..
]
}
}
※ なおownerが友人ではない場合、fieldsパラメータの指定にかかわらずthumbnailUrl、profileUrlは返されません。またattendeesには友人のみ含まれます。
個々のエントリに含まれる情報は、以下のとおりです。
| 属性名 | 説明 |
|---|---|
| id | スケジュールを特定するためのID (Schedule-ID) |
| startDatetime | 開始日時 |
| title | タイトル |
| description | 説明文 |
| privacy | 公開範囲。詳細については下記を参照してください。 |
| owner | スケジュール作成者 |
| owner.id | 作成者のID |
| owner.displayName | 作成者の表示名 |
| owner.thumbnailUrl | 作成者のサムネイル画像のURL |
| owner.profileUrl | 作成者のプロフィール画像のURL |
| attendees | スケジュール参加者（配列） |
| attendees.id | 参加者のID |
| attendees.displayName | 作成者の表示名 |
| attendees.thumbnailUrl | 参加者のサムネイル画像のURL |
| attendees.profileUrl | 参加者のプロフィール画像のURL |
"privacy" パラメーターの形式
そのスケジュールの公開範囲は、privacyパラメータ値で得られます。このprivacyパラメータは、更にvisibilityパラメータを持ちます。公開範囲の種別は、visibilityパラメータ値により表現されます。
visibilityパラメータ値の一覧は以下となります。
| 指定値 | 意味 |
|---|---|
| everyone | 全体に公開 |
| friends | 友人まで公開 |
| friends_of_friends | 友人の友人まで公開 |
| top_friends | 仲良しに公開 |
| group | 特定のグループにのみ公開 |
| user | 特定のユーザにのみ公開 |
| access_key | 合言葉にして公開 |
| self | 非公開 |
スケジュールの取得（範囲指定）
開始日時の範囲を指定してスケジュールを取得するためのURIは以下となります。
GET https://api.mixi-platform.com/2/calendar/schedules/[User-ID]/[Group-ID]?startDatetimeMin=[DATETIME]
| パラメータ名 | 指定する値 |
|---|---|
| User-ID | 認可ユーザのユーザID、および認可ユーザ自身を示す"@me"、または友人のユーザID。スケジュールの作成者を指定する。 |
| Group-ID | "@self"もしくは"@friends"もしくは"@all"。 |
※ なお、友人の友人たちの予定は取得できません。つまり /calendar/schedule/[友人のUID]/@friends という指定はエラーになります。
さらに、以下のクエリパラメータをサポートしています。
| パラメータ名 | 説明 |
|---|---|
| startDatetimeMin | 開始日の最小値。必須パラメータです。w3cdtf-formatで指定してください。 |
| startDatetimeMax | 開始日の最大値。w3cdtf-formatで指定してください。省略した場合はstartDatetimeMinで指定された日付の23:59:59までとみなされます。 |
| fields | 取得したい情報の項目をカンマ区切りで指定します。 指定可能な項目名は「description,privacy,owner,owner.thumbnailUrl,owner.profileUrl, attendees,attendees.thumbnailUrl,attendees.profileUrl」です。もしfieldsパラメータを省略した場合には、「privacy,owner,owner.thumbnailUrl,owner.profileUrl」が指定されたと見なされます。start_timeとtitleについては、必ず結果に含まれます。 またowner,attendeesを指定した場合はそれぞれowner.id,owner.displayNameとattendees.id,attendees.displayNameが必ず結果に含まれます。 |
正常に取得できた場合は、以下のような結果を得ることができます。
{
"entry":[
{
"id":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"start_time":"2012-01-01T00:00:00+09:00",
"title":"お正月",
"description":"あけましておめでとうございます",
"privacy":{
"visibility":"public"
},
"owner":{
"id":"xxxxxxxxxxxxx",
"displayName":"表示名",
"thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
"profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
},
"attendees":[
{
"id":"xxxxxxxxxxxxx",
"displayName":"表示名",
"thumbnailUrl":"http://ic.photo.mixi.jp/v/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxx/picture/xxxxxxxxxxxxxx_999999_99small.jpg",
"profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
},
..以下略..
],
},
..以下略..
}
個々のエントリに含まれる情報は、以下のとおりです。
| 属性名 | 説明 |
|---|---|
| id | スケジュールを特定するためのID (Schedule-ID) |
| startDatetime | 開始日時 |
| title | タイトル |
| description | 説明文 |
| privacy | 公開範囲。詳細については上記を参照してください。 |
| owner | 作成者 |
| owner.id | 作成者のID |
| owner.displayName | 作成者の表示名 |
| owner.thumbnailUrl | 作成者のサムネイル画像のURL |
| owner.profileUrl | 作成者のプロフィール画像のURL |
| attendees | 参加者（配列） |
| attendees.id | 参加者のID |
| attendees.displayName | 作成者の表示名 |
| attendees.thumbnailUrl | 参加者のサムネイル画像のURL |
| attendees.profileUrl | 参加者のプロフィール画像のURL |
※ なおownerが友人ではない場合、fieldsパラメータの指定にかかわらずthumbnailUrl、profileUrlは返されません。またattendeesには友人のみ含まれます。
スケジュールの投稿
スケジュールを投稿するためのURIは以下となります。
POST https://api.mixi-platform.com/2/calendar/schedules/[User-ID]/@self
| パラメータ名 | 指定する値 |
|---|---|
| User-ID | 認可ユーザのユーザID、および認可ユーザ自身を示す"@me" |
Content-Typeリクエストヘッダには"application/json"を指定し、 登録するスケジュールは、リクエストボディとしてJSONを指定します。具体的には、以下のようなリクエストとなります。
{
"startDatetimes":"2012-01-01T00:00:00+09:00",
"title":"お正月",
"description":"あけましておめでとうございます",
"invite":"0",
"privacy":{
"visibility":"everyone"
},
"attendees":[
"member0001",
"member0002",
"member0003"
]
}
※ inviteは参加者を募集するかどうかを"0"か"1"で指定してください。
スケジュールの投稿に成功した場合は、ステータスコード201、およびそのスケジュールを特定するためのIDを持つ以下のようなJSON文字列が返却されます。
{
"id" : "73a1354313a8dced1ca07a68c1204b3d727042d048"
}
スケジュールへの参加
スケジュールに参加するためのURIは以下となります。
PUT https://api.mixi-platform.com/2/calendar/attendees/[User-ID]/@self/[Schedule-ID]
| パラメータ名 | 指定する値 |
|---|---|
| User-ID | 友人のユーザID。スケジュールの作成者を指定する。 |
| Schedule-ID | 参加対象のスケジュールID。 |
スケジュールの参加に成功した場合は、ステータスコード201が返却されます。
{
"id" : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"attendees" : [
"xxxxxxxxxxxxx"
]
}
個々のエントリに含まれる情報は、以下のとおりです。
| 属性名 | 説明 |
|---|---|
| id | スケジュールを特定するためのID (Schedule-ID) |
| attendees | 新しく追加された参加者（配列） |