创建订阅

命名空间：microsoft.graph

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

若要确定可为其创建订阅的资源和订阅限制，请参阅 设置资源数据更改通知：支持的资源。

某些资源支持丰富的通知，即包含资源数据的通知。 有关这些资源的详细信息，请参阅 设置包含资源数据的更改通知：支持的资源。

此 API 可用于以下国家级云部署。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

创建订阅需要读取资源范围。 例如，若要获取更改消息通知，应用需要 Mail.Read 权限。

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

支持的资源	委派（工作或学校帐户）	委派（个人 Microsoft 帐户）	应用程序
callRecord (/communications/callRecords)	不支持	不支持	CallRecords.Read.All
callRecording communications/onlineMeetings/getAllRecordings 组织中的所有录制内容。	不支持。	不支持。	OnlineMeetingRecording.Read.All
callRecording communications/onlineMeetings/{onlineMeetingId}/recordings 特定会议的所有录制。	OnlineMeetingRecording.Read.All	不支持。	OnlineMeetingRecording.Read.All
callRecording users/{userId}/onlineMeetings/getAllRecordings 在由特定用户组织的会议中可用的通话记录。	OnlineMeetingRecording.Read.All	不支持。	OnlineMeetingRecording.Read.All
callTranscript communications/onlineMeetings/getAllTranscripts 组织中的所有脚本。	不支持。	不支持。	OnlineMeetingTranscript.Read.All
callTranscript communications/onlineMeetings/{onlineMeetingId}/transcripts 特定会议的所有脚本。	OnlineMeetingTranscript.Read.All	不支持。	OnlineMeetingTranscript.Read.All
callTranscript users/{userId}/onlineMeetings/getAllTranscripts 在由特定用户组织的会议中可用的通话记录。	OnlineMeetingTranscript.Read.All	不支持。	OnlineMeetingTranscript.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
聊天 /appCatalogs/teamsApps/{id}/installedToChats 安装了特定 Teams 应用的组织中所有聊天。	不支持	不支持	Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled
chatMessage (/teams/{id}/channels/{id}/messages)	ChannelMessage.Read.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
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 安装特定 Teams 应用的组织中所有聊天的聊天消息。	不支持	不支持	Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled
联系人	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 /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 安装特定 Teams 应用的组织中所有聊天的聊天成员。	不支持。	不支持。	ChatMember.Read.WhereInstalled、ChatMember.ReadWrite.WhereInstalled、Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled
conversationMember (/teams/{id}/members)	TeamMember.Read.All	不支持	TeamMember.Read.All
conversationMember (/teams/{id}/channels/getAllMembers)	不支持	不支持	ChannelMember.Read.All
driveItem（用户的个人 OneDrive）	不支持	Files.Read	不支持
driveItem (OneDrive for Business)	Files.Read.All	不支持	Files.Read.All
事件	Calendars.Read	Calendars.Read	Calendars.Read
组	Group.Read.All	不支持	Group.Read.All
组对话	Group.Read.All	不支持	不支持
列表	Sites.Read.All	不支持	Sites.Read.All
邮件	Mail.ReadBasic、Mail.Read	Mail.ReadBasic、Mail.Read	Mail.Read
offerShiftRequest (/teams/{id}/schedule/offerShiftRequests) 对团队中任何产品/服务转移请求的更改。	Schedule.Read.All、Schedule.ReadWrite.All	不支持。	Schedule.Read.All、Schedule.ReadWrite.All
openShiftChangeRequest (/teams/{id}/schedule/openShiftChangeRequests) 对团队中任何未结的班次请求的更改。	Schedule.Read.All、Schedule.ReadWrite.All	不支持。	Schedule.Read.All、Schedule.ReadWrite.All
状态	Presence.Read.All	不支持	不支持
打印机	不支持	不支持	打印机。阅读.All，Printer.ReadWrite.All
printTaskDefinition	不支持	不支持	PrintTaskDefinition.ReadWrite.All
安全警报	SecurityEvents.ReadWrite.All	不支持	SecurityEvents.ReadWrite.All
shift (/teams/{id}/schedule/shifts) 对团队中任何班次的更改。	Schedule.Read.All、Schedule.ReadWrite.All	不支持。	Schedule.Read.All、Schedule.ReadWrite.All
swapShiftsChangeRequest (/teams/{id}/schedule/swapShiftsChangeRequests) 对团队中任何交换班次请求的更改。	Schedule.Read.All、Schedule.ReadWrite.All	不支持。	Schedule.Read.All、Schedule.ReadWrite.All
团队（/teams - 组织中的所有团队）	不支持	不支持	Team.ReadBasic.All，TeamSettings.Read.All
团队 (/teams/{id})	Team.ReadBasic.All，TeamSettings.Read.All	不支持	Team.ReadBasic.All，TeamSettings.Read.All
timeOffRequest (/teams/{id}/schedule/timeOffRequests) 对团队中任何休假请求的更改。	Schedule.Read.All、Schedule.ReadWrite.All	不支持。	Schedule.Read.All、Schedule.ReadWrite.All
todoTask	Tasks.ReadWrite	Tasks.ReadWrite	不支持
user	User.Read.All	User.Read.All	User.Read.All
virtualEventWebinar	VirtualEvent.Read	不支持。	VirtualEvent.Read.All

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

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

chatMessage

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

必须使用 Prefer: include-unknown-enum-members 请求标头在 chatMessagemessageType可进化枚举中获取以下值： systemEventMessage for /teams/{id}/channels/{id}/messages 和 /chats/{id}/messages resource。

注意

/teams/getAllMessages、 /chats/getAllMessages、 /me/chats/getAllMessages、 /users/{id}/chats/getAllMessages和 /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 是按流量计费的 API; 付款模式和许可要求 可能适用。 /teams/getAllMessages和 /chats/getAllMessages 都支持 和 model=B 支付模型、/me/chats/getAllMessages、 /users/{id}/chats/getAllMessages和 /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 仅model=B支持 。model=A 如果未在查询中指定付款模型，将使用默认 评估模式 。

注意

若要为已订阅的更改通知资源添加或更改付款模型，必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。

conversationMember

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

注意

/teams/getAllMembers、 /chats/getAllMembers和 /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 是按流量计费的 API; 付款模式和许可要求 可能适用。 /teams/getAllMembers 和 /chats/getAllMembers 都 model=A 支持 和 model=B 支付模型。 /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 仅 model=B支持 。 如果未在查询中指定付款模型，将使用默认 评估模式 。

注意

若要为已订阅的更改通知资源添加或更改付款模型，必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。

团队、频道和聊天

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

订阅特定聊天或用户级别的更改时，可以使用 notifyOnUserSpecificProperties 查询字符串参数。 在创建订阅期间将查询字符串参数 notifyOnUserSpecificPropertiestrue 设置为 时，会将两种类型的有效负载发送到订阅服务器。 一种类型包含特定于用户的属性，另一种类型在发送时不使用它们。 有关详细信息，请参阅 使用 Microsoft Graph 获取聊天更改通知。

注意

/appCatalogs/teamsApps/{id}/installedToChats 具有 许可和付款要求，特别是仅 model=B支持 。 如果未指定模型，将使用评估模式。

注意

若要为已订阅的更改通知资源添加或更改付款模型，必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。

请求示例

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

POST https://graph.microsoft.com/v1.0/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 联系人、事件或消息资源中的更改。

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

• 委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。 例如，不能使用委托的权限 Calendars.Read 订阅其他用户邮箱中的事件。

• 订阅共享或委托文件夹中 Outlook 联系人、事件或邮件的更改通知：

  • 使用相应的应用程序权限订阅租户内任何用户的文件夹或邮箱中项目的更改。
  • 请勿使用 Outlook 共享权限 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其读/写权限) ，因为它们 不支持 订阅共享或委派文件夹中项目的更改通知。

状态

状态 上的订阅要求对更改通知中包含的任何资源数据进行加密。 在 创建订阅 时始终指定 encryptionCertificate 参数以避免失败。 请参阅有关 设置更改通知以包含资源数据 的详细信息。

virtualEventWebinar

虚拟事件的订阅仅支持基本通知，并且仅限于虚拟事件的几个实体。 有关支持的订阅类型的详细信息，请参阅 获取Microsoft Teams 虚拟事件更新的更改通知。

HTTP 请求

POST /subscriptions

请求标头

名称	类型	说明
Authorization	string	持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

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

响应

如果成功，此方法在响应正文中返回 201 Created 响应代码和 subscription 对象。 要详细了解错误返回方式，请参阅错误响应。

示例

请求

以下示例演示了在用户收到新邮件时发送更改通知的请求。

HTTP

POST https://graph.microsoft.com/v1.0/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"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = 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",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

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

CLI

mgc subscriptions create --body '{\
   "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"\
}\
'

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

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.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) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

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

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/send/myNotifyClient");
subscription.setResource("me/mailFolders('Inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-11-20T18:23:45.9356913Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("secretClientValue");
subscription.setLatestSupportedTlsVersion("v1_2");
Subscription result = graphClient.subscriptions().post(subscription);

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

JavaScript

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')
	.post(subscription);

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

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('created');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/send/myNotifyClient');
$requestBody->setResource('me/mailFolders(\'Inbox\')/messages');
$requestBody->setExpirationDateTime(new \DateTime('2016-11-20T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');
$requestBody->setLatestSupportedTlsVersion('v1_2');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

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

PowerShell

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 文档。

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	change_type = "created",
	notification_url = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	resource = "me/mailFolders('Inbox')/messages",
	expiration_date_time = "2016-11-20T18:23:45.9356913Z",
	client_state = "secretClientValue",
	latest_supported_tls_version = "v1_2",
)

result = await graph_client.subscriptions.post(request_body)

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

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

重复订阅行为

不允许重复订阅。 当订阅请求包含与现有订阅包含的 changeType 和 资源 相同的值时，请求失败并显示 HTTP 错误代码 409 Conflict和错误消息 Subscription Id <> already exists for the requested combination。

资源示例

订阅资源属性的有效值如下：

资源类型	示例
通话记录	communications/callRecords
callRecording	communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings
callTranscript	communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts
聊天消息	chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
联系人	me/contacts
对话	groups('{id}')/conversations
驱动器	me/drive/root
事件	me/events
组	groups
列表	sites/{site-id}/lists/{list-id}
邮件	me/mailfolders('inbox')/messages, me/messages
状态	/communications/presences/{id}（单个用户），/communications/presences?$filter=id in ('{id}','{id}',…)（多个用户）
打印机	print/printers/{id}/jobs
PrintTaskDefinition	print/taskDefinitions/{id}/tasks
安全警报	security/alerts?$filter=status eq 'New'
todoTask	/me/todo/lists/{todoTaskListId}/tasks
用户	users

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

响应

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$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 请求无效”。