创建订阅

项目
07/18/2022

命名空间：microsoft.graph

重要

Microsoft Graph版本下的 /beta API 可能会发生更改。不支持在生产应用程序中使用这些 API。若要确定 API 是否在 v1.0 中可用，请使用版本选择器。

注意

应更新将此功能与 baseTask 或 baseTaskList 配合使用的现有应用，因为基于这些资源构建的待办 API 集自 2022 年 5 月 31 日起已弃用。该 API 集将于 2022 年 8 月 31 日停止返回数据。请使用基于 todoTask 构建的 API 集。

订阅侦听器应用程序，以在 Microsoft Graph 中指定资源发生的更改属于请求的更改类型时接收更改通知。

请参阅" 权限部分中的表格，了解支持订阅以更改通知的资源列表。

某些资源支持在更改通知中包括加密资源数据的选项。这些资源包括 chatMessage、联系人、事件、消息、 onlineMeetings 和状态。有关详细信息，请参阅设置包含资源数据的更改通知和 Microsoft Graph 中 Outlook 资源的更改通知。

权限

创建订阅需要对资源的读取权限。例如，若要获取有关邮件的更改通知，应用需要 Mail.Read 权限。

根据请求的资源和权限类型（委托或应用程序），下表中指定的权限为调用此 API 所需的最小权限。要了解详细信息，包括在选择权限之前的注意事项，可在权限中搜索以下权限。

支持的资源	委派（工作或学校帐户）	委派（个人 Microsoft 帐户）	应用程序
baseTask (已弃用)	Tasks.ReadWrite	Tasks.ReadWrite	不支持
callRecord (/communications/callRecords)	不支持	不支持	CallRecords.Read.All
频道（/teams/getAllChannels – 组织中的所有频道）	不支持	不支持	Channel.ReadBasic.All，ChannelSettings.Read.All
频道 (/teams/{id}/channels)	Channel.ReadBasic.All，ChannelSettings.Read.All	不支持	Channel.ReadBasic.All，ChannelSettings.Read.All
聊天（/chats - 组织中的所有聊天）	不支持	不支持	Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
聊天 (/chats/{id})	Chat.ReadBasic, Chat.Read, Chat.ReadWrite	不支持	ChatSettings.Read.Chat 、ChatSettings.ReadWrite.Chat、Chat.Manage.Chat*、Chat.ReadBasic.All、Chat.Read.All、Chat.ReadWrite.All
chatMessage (/teams/{id}/channels/{id}/messages)	ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.All	不支持	ChannelMessage.Read.Group*、ChannelMessage.Read.All
chatMessage（/teams/getAllMessages -- 组织中所有频道消息）	不支持	不支持	ChannelMessage.Read.All
chatMessage (/chats/{id}/messages)	Chat.Read、Chat.ReadWrite	不支持	Chat.Read.All
chatMessage（/chats/getAllMessages -- 组织中所有聊天消息）	不支持	不支持	Chat.Read.All
chatMessage（/users/{id}/chats/getAllMessages - 特定用户所属所有聊天的聊天消息）	Chat.Read、Chat.ReadWrite	不支持	Chat.Read.All、Chat.ReadWrite.All
联系人	Contacts.Read	Contacts.Read	Contacts.Read
conversationMember (/chats/getAllMembers)	不支持	不支持	ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All.
conversationMember (/chats/{id}/members)	ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite	不支持	ChatMember.Read.Chat 、Chat.Manage.Chat、ChatMember.Read.All、ChatMember.ReadWrite.All、Chat.ReadBasic.All、Chat.Read.All、Chat.ReadWrite.All
conversationMember (/teams/getAllMembers)	不支持	不支持	TeamMember.Read.All, TeamMember.ReadWrite.All
conversationMember (/teams/{id}/members)	TeamMember.Read.All	不支持	TeamMember.Read.All
conversationMember (/teams/{id}/channels/getAllMembers)	不支持	不支持	ChannelMember.Read.All
driveItem（用户的个人 OneDrive）	不支持	Files.ReadWrite	不支持
driveItem (OneDrive for Business)	Files.ReadWrite.All	不支持	Files.ReadWrite.All
事件	Calendars.Read	Calendars.Read	Calendars.Read
组	Group.Read.All	不支持	Group.Read.All
组对话	Group.Read.All	不支持	不支持
列表	Sites.ReadWrite.All	不支持	Sites.ReadWrite.All
邮件	Mail.ReadBasic、Mail.Read	Mail.ReadBasic、Mail.Read	Mail.Read
联机会议	不支持	不支持	OnlineMeetings.Read.All、OnlineMeetings.ReadWrite.All
状态	Presence.Read.All	不支持	不支持
打印机	不支持	不支持	打印机。阅读.All，Printer.ReadWrite.All
printTaskDefinition	不支持	不支持	PrintTaskDefinition.ReadWrite.All
安全警报	SecurityEvents.ReadWrite.All	不支持	SecurityEvents.ReadWrite.All
团队（/teams - 组织中的所有团队）	不支持	不支持	Team.ReadBasic.All，TeamSettings.Read.All
团队 (/teams/{id})	Team.ReadBasic.All，TeamSettings.Read.All	不支持	Team.ReadBasic.All，TeamSettings.Read.All
todoTask	Tasks.ReadWrite	Tasks.ReadWrite	不支持
user	User.Read.All	User.Read.All	User.Read.All

建议使用上表中记载的权限。由于安全限制，Microsoft Graph 订阅在只需要读取访问权限时将不支持写入访问权限。

注意：标有 * 的权限用于特定于资源的同意。

chatMessage

可以指定 chatMessage 订阅以包含资源数据。如果指定为包含资源数据（将 includeResourceData 设置为 true），则需要 encryption。如果没有为此类订阅指定 encryptionCertificate，则订阅创建将失败。在可以使用应用程序权限创建 chatMessage 订阅之前，可能需要请求访问权限。有关详细信息，请参阅 Microsoft Teams 中的受保护 API。

必须使用 Prefer: include-unknown-enum-members 请求标头以 chatMessage messageType evolvable enum 中获取以下值：适用于 /teams/{id}/channels/{id}/messages 和 /chats/{id}/messages 的 systemEventMessage。

备注

/teams/getAllMessages、/chats/getAllMessages、/me/chats/getAllMessages和/users/{id}/chats/getAllMessages具有许可和付款要求。 /teams/getAllMessages和/chats/getAllMessages支持model=A和model=B查询参数，/me/chats/getAllMessages和/users/{id}/chats/getAllMessages仅支持model=B。如果未指定模型，将使用评估模式。

conversationMember

可以指定 conversationMember 订阅以包含资源数据。如果指定为包含资源数据（将 includeResourceData 设置为 true），则需要 encryption。如果未指定 encryptionCertificate，则订阅创建将失败。

备注

/teams/getAllMembers 和 /chats/getAllMembers 具有许可和付款要求。 /teams/getAllMembers 和 /chats/getAllMembers 同时支持 model=A 和 model=B 查询参数。如果未指定模型，将使用评估模式。

团队、频道和聊天

可以指定团队、频道和聊天订阅以包含资源数据。如果指定为包含资源数据（将 includeResourceData 设置为 true），则需要 encryption。如果未指定 encryptionCertificate，则订阅创建将失败。

请求示例

在请求正文中的资源内指定 model 查询参数。

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "chats/getAllMessages?model=A",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

driveItem

其他限制适用于 OneDrive 项目的订阅。这些限制适用于订阅的创建和管理（获取、更新和删除）。

在个人 OneDrive 上，可订阅根文件夹或该驱动器中的任何子文件夹。在 OneDrive for Business 上，只可以订阅根文件夹。对订阅的文件夹或者其层次结构中的任何文件、文件夹或其他 driveItem 实例所做更改属于请求的更改类型时，发送更改通知。无法订阅不是文件夹的“驱动器”或“driveItem”实例，例如单个文件。

OneDrive for Business 和 SharePoint 支持向应用程序发送有关在 driveItem 上发生的安全事件通知。若要订阅这些事件，请为请求添加 prefer:includesecuritywebhooks 标头以创建订阅。创建订阅后，当项目权限更改时，你将收到通知。此标头适用于 SharePoint 和 OneDrive for Business 帐户，但不适用于 OneDrive 消费者版本的帐户。

联系人、事件和消息

可以订阅 Outlook 联系人、事件或消息资源中的更改，并在 POST 请求有效负载中选择性地指定是否在通知中包含加密的资源数据。

创建和管理（获取、更新和删除）订阅需要资源的读取范围。例如，若要获取有关邮件的更改通知，应用需要 Mail.Read 权限。 Outlook 更改通知支持委派和应用程序权限范围。请注意以下限制：

委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。例如，不能使用委托的权限 Calendars.Read 来订阅另一个用户邮箱中的事件。
订阅 共享或委托 文件夹中 Outlook 联系人、事件或邮件的更改通知：
- 使用相应的应用程序权限订阅租户内任何用户的文件夹或邮箱中项目的更改。
- 切勿使用 Outlook 共享权限（Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其相应的读写权限），因为它们不支持订阅对共享或委托文件夹中的项的更改通知。

onlineMeetings，状态

在使用加密资源数据创建通知订阅时，OnlineMeetings 和状态上的订阅需要 encryptionCertificate 和 encryptionCertificateId 属性。有关详细信息，请参阅设置更改通知以包含资源数据。有关联机会议订阅的详细信息，请参阅获取联机会议的更改通知。

HTTP 请求

POST /subscriptions

请求标头

名称	类型	说明
Authorization	string	Bearer {token}。必需。

请求正文

在请求正文中，提供 subscription 对象的 JSON 表示形式。

响应

如果成功，此方法在响应正文中返回 201 Created 响应代码和订阅对象。

要详细了解错误返回方式，请参阅错误响应。

示例

请求

在请求正文中，提供 subscription 对象的 JSON 表示形式。 clientState 和 latestSupportedTlsVersion 是可选字段。

此请求为当前已登录用户收到的新邮件的更改通知创建订阅。

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var subscription = new Subscription
{
    ChangeType = "created",
    NotificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    Resource = "me/mailFolders('Inbox')/messages",
    ExpirationDateTime = DateTimeOffset.Parse("2016-11-20T18:23:45.9356913Z"),
    ClientState = "secretClientValue",
    LatestSupportedTlsVersion = "v1_2"
};

await graphClient.Subscriptions
    .Request()
    .AddAsync(subscription);

重要

Microsoft Graph SDK 默认使用 v1.0 版本的 API，并且不支持 beta 版本中提供的所有类型、属性和 API。有关使用 SDK 访问 beta API 的详细信息，请参阅将 Microsoft Graph SDK 与 beta API 配合使用。

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


const options = {
    authProvider,
};

const client = Client.init(options);

const subscription = {
   changeType: 'created',
   notificationUrl: 'https://webhook.azurewebsites.net/api/send/myNotifyClient',
   resource: 'me/mailFolders(\'Inbox\')/messages',
   expirationDateTime: '2016-11-20T18:23:45.9356913Z',
   clientState: 'secretClientValue',
   latestSupportedTlsVersion: 'v1_2'
};

await client.api('/subscriptions')
    .version('beta')
    .post(subscription);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/subscriptions"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

MSGraphSubscription *subscription = [[MSGraphSubscription alloc] init];
[subscription setChangeType:@"created"];
[subscription setNotificationUrl:@"https://webhook.azurewebsites.net/api/send/myNotifyClient"];
[subscription setResource:@"me/mailFolders('Inbox')/messages"];
[subscription setExpirationDateTime: "2016-11-20T18:23:45.9356913Z"];
[subscription setClientState:@"secretClientValue"];
[subscription setLatestSupportedTlsVersion:@"v1_2"];

NSError *error;
NSData *subscriptionData = [subscription getSerializedDataWithError:&error];
[urlRequest setHTTPBody:subscriptionData];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "created";
subscription.notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient";
subscription.resource = "me/mailFolders('Inbox')/messages";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-11-20T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";
subscription.latestSupportedTlsVersion = "v1_2";

graphClient.subscriptions()
    .buildRequest()
    .post(subscription);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := msgraphsdk.NewSubscription()
changeType := "created"
requestBody.SetChangeType(&changeType)
notificationUrl := "https://webhook.azurewebsites.net/api/send/myNotifyClient"
requestBody.SetNotificationUrl(&notificationUrl)
resource := "me/mailFolders('Inbox')/messages"
requestBody.SetResource(&resource)
expirationDateTime, err := time.Parse(time.RFC3339, "2016-11-20T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime)
clientState := "secretClientValue"
requestBody.SetClientState(&clientState)
latestSupportedTlsVersion := "v1_2"
requestBody.SetLatestSupportedTlsVersion(&latestSupportedTlsVersion)
result, err := graphClient.Subscriptions().Post(requestBody)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
    ChangeType = "created"
    NotificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient"
    Resource = "me/mailFolders('Inbox')/messages"
    ExpirationDateTime = [System.DateTime]::Parse("2016-11-20T18:23:45.9356913Z")
    ClientState = "secretClientValue"
    LatestSupportedTlsVersion = "v1_2"
}

New-MgSubscription -BodyParameter $params

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

在请求正文中，提供 subscription 对象的 JSON 表示形式。clientState 和 latestSupportedTlsVersion 字段是可选的。

资源示例

下面是资源属性的有效值。

资源类型	示例
baseTask (已弃用)	`/me/tasks/lists/{Id}/tasks`
通话记录	`communications/callRecords`
渠道	`/teams/getAllChannels`, `/teams/{id}/channels`
聊天	`/chats`, `/chats/{id}`
聊天消息	`chats/{id}/messages`, `chats/getAllMessages`, `teams/{id}/channels/{id}/messages`, `teams/getAllMessages`
联系人	`me/contacts`
ConversationMember	`/chats/{id}/members`, `/chats/getAllMembers`, `/teams/{id}/members`, `/teams/getAllMembers`, `/teams/{id}/channels/getAllMembers`
对话	`groups('{id}')/conversations`
驱动器	`me/drive/root`
事件	`me/events`
组	`groups`
列表	`sites/{site-id}/lists/{list-id}`
邮件	`me/mailfolders('inbox')/messages`, `me/messages`
OnlineMeetings	`/communications/onlineMeetings/?$filter=JoinWebUrl eq '{JoinWebUrl}'`
状态	`/communications/presences/{id}`（单个用户），`/communications/presences?$filter=id in ('{id}','{id}',…)`（多个用户）
打印机	`print/printers/{id}/jobs`
PrintTaskDefinition	`print/taskDefinitions/{id}/tasks`
Teams	`/teams`, `/teams/{id}`
用户	`users`
todoTask	`/me/todo/lists/{todoTaskListId}/tasks`
安全警报	`security/alerts?$filter=status eq 'NewAlert'`

注意： 以 me 开头的任何路径也可与 users/{id}（而不是 me）一起使用，从而以特定用户为目标，而不是以当前用户为目标。

响应

以下示例显示了相应的响应。

注意： 为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "notificationContentType": "application/json"
}

通知终结点验证

notificationUrl 属性中指定的订阅通知终结点 () 必须能够响应验证请求，如为用户数据更改设置通知中所述。如果验证失败，创建订阅请求返回错误“400 请求无效”。

创建订阅

权限

chatMessage

conversationMember

团队、频道和聊天

请求示例

driveItem

联系人、事件和消息

onlineMeetings，状态

HTTP 请求

请求标头

请求正文

响应

示例

请求

资源示例

响应

通知终结点验证

反馈