创建订阅

项目
01/14/2024

命名空间：microsoft.graph

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

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

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

全局服务	美国政府 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.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
状态	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.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，则订阅创建将失败。

注意

/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 对象。要详细了解错误返回方式，请参阅错误响应。

示例

请求

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

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"
}


// 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);


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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"\
}\
'



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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) 

subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)


// 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);


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);


<?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();


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


from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription

graph_client = GraphServiceClient(credentials, scopes)

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)

在请求正文中，提供 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`

响应

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

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 请求无效”。

创建订阅

权限

chatMessage

conversationMember

团队、频道和聊天

请求示例

driveItem

联系人、事件和消息

状态

virtualEventWebinar

HTTP 请求

请求标头

请求正文

响应

示例

请求

重复订阅行为

资源示例

响应

通知终结点验证

反馈

反馈

其他资源