更新订阅

命名空间：microsoft.graph

重要

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

通过延长到期时间续订订阅。

“权限”部分中的表列出了支持订阅更改通知的资源。

订阅在一段时间后过期，时间长度因资源类型而异。 为了避免缺少更改通知，应用应在到期日期之前提前续订其订阅。 有关每种资源类型的订阅的最大长度，请参阅订阅。

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

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

权限

根据请求的资源和权限类型（委托或应用程序），下表中指定的权限为调用此 API 所需的最小权限。 若要了解其他信息， 在 特权权限之前要特别小心，在"权限" 中搜索。

注意

某些资源在多种方案中支持更改通知，其中每个方案可能需要不同的权限。 在这些情况下，请使用资源路径来区分方案。

支持的资源	委派（工作或学校帐户）	委派（个人 Microsoft 帐户）	应用程序
callRecord	不支持。	不支持。	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
callRecording appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings 在安装了特定 Teams 应用的会议中可用的通话记录。	不支持。	不支持。	OnlineMeetingRecording.Read.All、OnlineMeetingRecording.Read.Chat
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
callTranscript appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts 在安装了特定 Teams 应用的会议中可用的通话记录。	不支持。	不支持。	OnlineMeetingTranscript.Read.All、OnlineMeetingTranscript.Read.Chat
频道 /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、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
chatMessage /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 安装特定 Teams 应用的组织中所有聊天的聊天消息。	不支持。	不支持。	Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled
contact	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/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
conversationMember /teams/getAllChannels/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
virtualEventWebinar	VirtualEvent.Read	不支持。	VirtualEvent.Read.All
baseTask (已弃用)	Tasks.ReadWrite	Tasks.ReadWrite	不支持。

注意

以下权限使用 特定于资源的许可：

• OnlineMeetingRecording.Read.Chat
• OnlineMeetingTranscript.Read.Chat
• ChatSettings.Read.Chat
• ChatSettings.ReadWrite.Chat
• Chat.Manage.Chat
• ChannelMessage.Read.Group
• ChatMember.Read.Chat

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 实例，例如单个文件。

联系人、事件和消息

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

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

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

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

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

onlineMeetings， 状态

onlineMeetings 和 状态 订阅需要对包含资源数据的通知 进行加密 。 如果在通知中需要资源数据，则如果未指定 encryptionCertificate 和 encryptionCertificateId ，则订阅创建失败。 有关状态和联机会议订阅的详细信息，请参阅获取 Microsoft Teams 中状态更新的更改通知和获取联机会议的更改通知。

virtualEventWebinar

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

HTTP 请求

PATCH /subscriptions/{id}

请求标头

名称	类型	说明
Authorization	string	持有者 {token}。 必填。

请求正文

在请求正文中，仅提供应更新的属性的值。 请求正文中未包含的现有属性会保留其以前的值，或者根据对其他属性值的更改重新计算。

下表指定可更新的属性。

名称	类型	说明
expirationDateTime	DateTimeOffset	指定订阅过期时的 UTC 日期和时间。 对于支持的最大订阅，时间长度因资源而异。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 subscription 对象。

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

示例

请求

以下示例显示了一个请求。

HTTP

PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-type: application/json

{
   "expirationDateTime":"2016-11-22T18:23:45.9356913Z"
}

C#

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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new Subscription
{
	ExpirationDateTime = DateTimeOffset.Parse("2016-11-22T18:23:45.9356913Z"),
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions["{subscription-id}"].PatchAsync(requestBody);

重要

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

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta subscriptions patch --subscription-id {subscription-id} --body '{\
   "expirationDateTime":"2016-11-22T18:23:45.9356913Z"\
}\
'

重要

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

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

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
expirationDateTime , err := time.Parse(time.RFC3339, "2016-11-22T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 

subscriptions, err := graphClient.Subscriptions().BySubscriptionId("subscription-id").Patch(context.Background(), requestBody, nil)

重要

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

有关如何将 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();
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-11-22T18:23:45.9356913Z");
subscription.setExpirationDateTime(expirationDateTime);
Subscription result = graphClient.subscriptions().bySubscriptionId("{subscription-id}").patch(subscription);

重要

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

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   expirationDateTime: '2016-11-22T18:23:45.9356913Z'
};

await client.api('/subscriptions/{id}')
	.version('beta')
	.update(subscription);

重要

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

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

PHP

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


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

$requestBody = new Subscription();
$requestBody->setExpirationDateTime(new \DateTime('2016-11-22T18:23:45.9356913Z'));

$result = $graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->patch($requestBody)->wait();

重要

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

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

PowerShell

Import-Module Microsoft.Graph.Beta.ChangeNotifications

$params = @{
	expirationDateTime = [System.DateTime]::Parse("2016-11-22T18:23:45.9356913Z")
}

Update-MgBetaSubscription -SubscriptionId $subscriptionId -BodyParameter $params

重要

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

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

Python

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

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	expiration_date_time = "2016-11-22T18:23:45.9356913Z",
)

result = await graph_client.subscriptions.by_subscription_id('subscription-id').patch(request_body)

重要

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

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

响应

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

HTTP/1.1 200 OK
Content-type: application/json

{
  "id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource":"me/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType":"created,updated",
  "clientState":"secretClientValue",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
  "expirationDateTime":"2016-11-22T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "encryptionCertificate": "",
  "encryptionCertificateId": "",
  "includeResourceData": false,
  "notificationContentType": "application/json"
}