Share via


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

Get a list of rooms

POST

/rooms/{roomId}/users

· 201: User joins the given chat room

User joins a given room

GET

/rooms/{roomId}/messages

· 200: Wrapped array/ transcript of chat messages from the given chat room

Gets room transcript

POST

/rooms/{roomId}/messages

· 201: Message posted to the given chat room

Send a message

DELETE

/rooms/{roomId}/users/me

· 200: User leaves the given chat room

Leave 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

Get list of users statuses

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