Team Rooms的REST API
[原文发表地址] REST API for Team Rooms
[原文发表时间] 2013-07-22
因为有一个人问过我这个问题，所以我决定发些东西。下面是关于Team Rooms的REST API 的 Word文档，这需要同时在已有的TFS和TFS2013预告版上生效。假如你对于这个文档的内容有什么反馈建议的话请告诉我。
这是一份非常早期的预览版，我们将在今年晚些时候正式发布它。它未完善，但是个开始 。希望它能带给你所需要了解的关于做一些基础的Team Room扩展的知识。最终我们会跟着例子做更多，但是现在我们正尝试着把TFS 2013的完善好。
Brian
ChatRoom Service
General Information
Service Name |
ChatRoom service |
Area |
Chat |
Version |
V1 |
Application URL |
N/A |
Account URL |
{account}.visualstudio.com/DefaultCollection/_apis/Chat |
描述
聊天室服务允许用户们通过团队聊天室去沟通交流。这种服务允许开发者中心的用户实时的和他们的团队成员进行沟通合作。
这个团队聊天室必须面向那些有效的扩展开放以允许它们之间的交流。它允许其它微软内的一些服务和外部的第三方Apps在这个Team Room里面进行以下的一些基本操作：
聊天室层面上的操作比如增加（或删除）聊天室，获取聊天室的名单，等等。
用户层面上的操作比如给一个聊天室增加（或删除）一个给定的用户。
消息层面上的操作比如发送一条信息，得到聊天纪录（最近的，给定日期的，给定时间间隔的）。
默认情况下聊天室服务自定义生成的聊天室存储在收藏夹层面上并且不会与TFS里面的任何一个团队冲突。然而我们会为每一个TFS团队自动生成一个聊天室。这个聊天室会被存储在这个团队的最常用之列并且展示在这个团队的主页上。
资源
资源 |
描述 |
/rooms |
表示聊天室资源容器 |
<RoomUri>/users |
表示聊天用户资源容器 |
<RoomUri>/messages |
表示聊天消息资源容器 |
API 流
一些常见流程如下：
用户加入给定团队聊天室一个通过指定用户身份验证的聊天客户端，得到一列聊天室的名单，加入一个指定的聊天室，检索副本信息，在这个聊天室里面发一条消息，离开这个聊天室。
动词 |
请求 & 响应 |
API Details |
GET |
/rooms · 200: Wrapped array of team room information |
|
POST |
/rooms/{roomId}/users · 201: User joins the given chat room |
|
GET |
/rooms/{roomId}/messages · 200: Wrapped array/ transcript of chat messages from the given chat room |
|
POST |
/rooms/{roomId}/messages · 201: Message posted to the given chat room |
|
DELETE |
/rooms/{roomId}/users/me · 200: User leaves the given chat room |
NOTE: Streaming APIs will come online at a later date
用户状态
一个通过指定用户身份验证的聊天客户端，会展示出目前在这个聊天室里面的用户的名单。对于其他的一些常规聊天操作，以上API有效。
动词 |
请求 & 响应 |
API Details |
GET |
/rooms/{roomId}/users · 200: Wrapped array of users currently online in the given chat room |
API 细节
这个部分包含每个web API的细节，每个独立的API经过一个状态的检查，一旦获得批准它会得到初始产品释放出来的V1状态。在完善过的文档当中这个会被覆盖到更细节的版本。
获取聊天室
检索给定账号里面的聊天室，这个账号里的信息通过给定的URL来检索。
Status |
V1 |
GET |
/chat/Rooms |
Params |
Check OData filters below |
Response Body |
{ "count": 2, "value": [ { "id": 1, "name": "First Room", "description": "RoomDescription", "lastActivity": "2013-04-11T00:32:29.673Z", "isClosed": false, "creatorUserTfId": "edfab9de-17c2-49ef-99cb-abfc159a1224", "createdDate": "2013-0411T00:32:29.673Z" } { "id": 2, "name": "Updated Room Name", "description": "Updated Description", "lastActivity": "2013-04-11T00:32:29.673Z", "isClosed": false, "creatorUserTfId": "edfab9de-17c2-49ef-99cb-abfc159a1224", "createdDate": "2013-0411T00:32:29.673Z" } ] } |
Return Codes |
200: OK – success |
创建聊天室
在给定的账号里面创建一个新的聊天室
Status |
V1 |
POST |
/Chat/Rooms |
Params |
{ "Name":"NewRoom", "Description":"Description1" } |
Response Body |
{ "id":2,"name":"NewRoom", "description":"Description1", "lastActivity":"2013-04-11T00:32, "creatorUserTfId":"edfab9de-17c2-49ef-99cb-abfc159a1224", "createdDate":"2013-04-11T00:32:29.673Z" } |
Return Codes |
201: Created – success |
获取聊天室信息
得到单个聊天室的信息例如名字、描述。
Status |
V1 |
GET |
/Chat/Rooms/{RoomId} |
Params |
|
Response Body |
{ "id": 2, "name": "Second Room", "description": "", "lastActivity": "2013-03-22T19:53:33.683Z", "isClosed": false, "creatorUserTfId":"4ea29d8a-00d9-4e76-b798-f6be3b0967c0", "createdDate": "2013-03-22T19:53:33.683Z" } |
Return Codes |
200: OK– success 404: Not Found- Room not found |
更新聊天室信息
更新一个给定的聊天室的信息例如名字，描述。
Status |
V1 |
PATCH |
/Chat/Rooms/{RoomId} |
Params |
{ "Name":"New Room Name", "Description":"Updated Description" } |
Response Body |
|
Return Codes |
200: OK– success 404: Not Found- Room not found |
删除聊天室
删除指定的聊天室.
Status |
NOT IMPLEMENTED YET |
DELETE |
/Chat/Rooms/{RoomId} |
Params |
|
Response Body |
|
Return Codes |
200: OK– success 404: Not Found - Room not found |
在聊天室中获取用户
获得当前在线的用户
Status |
V1 |
GET |
/Chat/Rooms/{RoomId}/Users |
Params |
Odata filters applicable here |
Response Body |
{ "count": 1, "value": [ { "roomId": 1, "userId": "b918ff7a-52f7-4bdf-8186-2d5cdbf707d7", "lastActivity": "2013-04-11T00:43:35.903Z", "joinedDate": "2013-04-11T00:43:35.903Z" } ] } |
Return Codes |
200: OK– success 404: Not Found - Room not found |
获取用户状态信息
在给定聊天室上下文中获取给定用户的状态。“me”资源是一个储存当前登录用户的特殊资源。
Status |
V1 |
GET |
/Chat/Rooms/{RoomId}/Users/UserId or /Chat/Rooms/{RoomId}/Users/me |
Params |
|
Response Body |
{ "roomId": 1, "userId": "b918ff7a-52f7-4bdf-8186-2d5cdbf707d7", "lastActivity": "2013-04-11T00:48:02.69Z", "joinedDate": "2013-04-11T00:48:02.69Z" } |
Return Codes |
200: OK– success 404: Not Found - Room not found/ user not present in room |
加入聊天室
把当前通过身份验证的用户加入到指定的团队里面
Status |
V1 |
PUT |
/Chat/Rooms/{RoomId}/Users/UserId or /Chat/Rooms/{RoomId}/Users/me |
Params |
{ "UserId": "b918ff7a-52f7-4bdf-8186-2d5cdbf707d7" } |
Response Body |
|
Return Codes |
200: OK– success 404: Not Found - Room not found |
离开聊天室
使当前通过身份验证的用户离开指定的聊天室
Status |
Review (Review, v1.preview, v1, etc…) |
DELETE |
/Chat/Rooms/{RoomId}/Users/UserId or /Chat/Rooms/{RoomId}/Users/me |
Params |
|
Response Body |
|
Return Codes |
200: OK– success 404: Not Found - Room not found/ user not present in room |
发送消息
发送一条信息到指定的聊天室
Status |
Review (Review, v1.preview, v1, etc…) |
POST |
/Chat/Rooms/{RoomId}/Messages |
Params |
{ "content": “Message content” } |
Response Body |
Location header contains message Id Rooms/{RoomId}/Messages/{MessageId} |
Return Codes |
201: Created – success 404: Not Found - Room not found |
获取聊天副本
得到指定聊天室的聊天副本
Status |
Review (Review, v1.preview, v1, etc…) |
GET |
/Chat/Rooms/{RoomId}/Messages |
Params |
Odata params applicable here |
Response Body |
{ "count": 2, "value": [ { "id": 97, "content": "First message in the room", "messageType": "normal", "postedTime": "2013-04-11T01:01:09.097Z", "postedRoomId": 1, "postedByUserTfid": "b918ff7a-52f7-4bdf-8186-2d5cdbf707d7" }, { "id": 98, "content": "Hello", "messageType": "normal", "postedTime": "2013-04-11T01:01:11.69Z", "postedRoomId": 1, "postedByUserTfid": "b918ff7a-52f7-4bdf-8186-2d5cdbf707d7" } ] } |
Return Codes |
200: OK– success 404: Not Found - Room not found |
获取特定信息
在指定的聊天室里面获取一条消息
Status |
V1 |
GET |
/Chat/Rooms/{RoomId}/Messages/{MessageId} |
Params |
|
Response Body |
{ "id": 97, "content": "First message in the room", "messageType": "normal", "postedTime": "2013-04-11T01:01:09.097Z", "postedRoomId": 1, "postedByUserTfid": "b918ff7a-52f7-4bdf-8186-2d5cdbf707d7" } |
Return Codes |
200: OK– success 404: Not Found - Room/Message not found |
更新特定信息
在指定的聊天室里面更新一条消息
Status |
NOT IMPLEMENTED YET |
PATCH |
/Chat/Rooms/{RoomId}/Messages/{MessageId} |
Params |
|
Response Body |
{ "message": “Message content” } |
Return Codes |
200: OK– success 404: Not Found - Room/Message not found |
删除特定信息
在指定聊天室里面删除一条消息
Status |
NOT IMPLEMENTED YET |
DELETE |
/Chat/Rooms/{RoomId}/Messages/{MessageId} |
Params |
|
Response Body |
|
Return Codes |
200: OK– success 404: Not Found - Room/Message not found |