订阅资源类型subscription resource type

借助订阅,客户端应用可以接收有关 Microsoft Graph 数据更改的通知。A subscription allows a client app to receive notifications about changes to data in Microsoft Graph. 目前,支持订阅以下资源:Currently, subscriptions are enabled for the following resources:

  • Outlook 中的[消息][]、事件联系人A message, event, or contact in Outlook
  • Office 365 组的对话A conversation of an Office 365 group
  • OneDrive for Business 中根文件夹driveItem 的层次结构中的内容,或用户个人 OneDrive 中的根文件夹或子文件夹 driveItem 的层次结构中的内容Content in the hierarchy of a root folder driveItem in OneDrive for Business, or of a root folder or subfolder driveItem in a user's personal OneDrive
  • Azure Active Directory 中的用户A user or group in Azure Active Directory
  • Microsoft Graph 安全性 API 中的警报An alert from the Microsoft Graph Security API

JSON 表示形式JSON representation

下面是资源的 JSON 表示形式。Here is a JSON representation of the resource.

{
  "changeType": "string",
  "notificationUrl": "string",
  "resource": "string",
  "applicationId" : "string",
  "expirationDateTime": "String (timestamp)",
  "id": "string (identifier)",
  "clientState": "string",
  "creatorId": "string"
}

属性Properties

属性Property 类型Type 说明Description
changeTypechangeType stringstring 必需。Required. 指示订阅资源中将引发通知的更改类型。Indicates the type of change in the subscribed resource that will raise a notification. 支持的值是:createdupdateddeletedThe supported values are: created, updated, deleted. 可以使用以逗号分隔的列表组合多个值。Multiple values can be combined using a comma-separated list.

注意:驱动器根项通知仅支持 updated changeType。Note: Drive root item notifications support only the updated changeType. 用户和组通知支持 updateddeleted changeType。User and group notifications support updated and deleted changeType.
notificationUrlnotificationUrl stringstring 必需。Required. 将接收通知的终结点的 URL。The URL of the endpoint that will receive the notifications. 该 URL 必须使用 HTTPS 协议。This URL must make use of the HTTPS protocol.
resourceresource stringstring 必需。Required. 指定要被监视以进行更改的资源。Specifies the resource that will be monitored for changes. 不包含的基 URL (https://graph.microsoft.com/v1.0/)。Do not include the base URL (https://graph.microsoft.com/v1.0/).
expirationDateTimeexpirationDateTime dateTimedateTime 必需。Required. 指定 webhook 订阅过期的日期和时间。Specifies the date and time when the webhook subscription expires. 时间为 UTC 时间,可以是距离订阅创建的一段时间(因订阅资源不同而异)。The time is in UTC, and can be an amount of time from subscription creation that varies for the resource subscribed to. 请参阅下表,了解支持的最长订阅有效期。See the table below for maximum supported subscription length of time.
clientStateclientState 字符串string 可选。Optional. 指定服务为每个通知发送的 clientState 属性的值。Specifies the value of the clientState property sent by the service in each notification. 最大长度为 128 个字符。The maximum length is 128 characters. 通过对比与订阅一起发送的 clientState 属性值和与每个通知一起接收的 clientState 属性值,客户端可以检查通知是否是由服务发送。The client can check that the notification came from the service by comparing the value of the clientState property sent with the subscription with the value of the clientState property received with each notification.
idid stringstring 订阅的唯一标识符。只读。Unique identifier for the subscription. Read-only.
applicationIdapplicationId stringstring 用于创建订阅的应用程序的标识符。Identifier of the application used to create the subscription. 只读。Read-only.
creatorIdcreatorId stringstring 已创建订阅的用户或服务主体的标识符。Identifier of the user or service principal that created the subscription. 如果此应用使用委派权限来创建订阅,则此字段包含该应用代表其调用的已登录用户的 ID。If the app used delegated permissions to create the subscription, this field contains the id of the signed-in user the app called on behalf of. 如果此应用使用应用程序权限,则此字段包含对应于该应用的服务主体的 ID。If the app used application permissions, this field contains the id of the service principal corresponding to the app. 只读。Read-only.

每个资源类型的最长订阅有效期Maximum length of subscription per resource type

资源Resource 最大过期时间Maximum Expiration Time
邮件Mail 4230 分钟(不到 3 天)4230 minutes (under 3 days)
日历Calendar 4230 分钟(不到 3 天)4230 minutes (under 3 days)
联系人Contacts 4230 分钟(不到 3 天)4230 minutes (under 3 days)
组对话Group conversations 4230 分钟(不到 3 天)4230 minutes (under 3 days)
驱动器根项Drive root items 4230 分钟(不到 3 天)4230 minutes (under 3 days)
安全警报Security alerts 43200分钟(不到 30 天)43200 minutes (under 30 days)

注意: 现有和新的应用都不得超过支持的这一上限值。Note: Existing applications and new applications should not exceed the supported value. 今后,任何超出最大值的订阅创建或续订请求都将失败。In the future, any requests to create or renew a subscription beyond the maximum value will fail.

关系Relationships

None

方法Methods

方法Method 返回类型Return Type 说明Description
创建订阅Create subscription 订阅subscription 订阅侦听器应用程序,在 Microsoft Graph 数据发生更改时接收通知。Subscribes a listener application to receive notifications when Microsoft Graph data changes.
更新订阅Update subscription 订阅subscription 通过更新其过期时间来续订订阅。Renews a subscription by updating its expiration time.
列出订阅List subscriptions 订阅subscription 列出有效订阅。Lists active subscriptions.
获取订阅Get subscription 订阅subscription 读取 subscription 对象的属性和关系。Reads properties and relationships of subscription object.
删除订阅Delete subscription None 删除订阅对象。Deletes a subscription object.