订阅资源类型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 中的联系人。Mail, events, and contacts from Outlook.
  • 来自 Office 组的对话。Conversations from Office Groups.
  • 从 OneDrive 驱动器根项目。Drive root items from OneDrive.
  • 用户和 Azure Active Directory 组。Users and Groups from Azure Active Directory.
  • 来自 Microsoft Graph 安全 API 的通知。Alerts 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.

注意: 驱动器根项目通知仅支持updatedchangeType。Note: Drive root item notifications support only the updated changeType. 用户和组通知支持updateddeletedchangeType。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 stringstring 可选。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.

RelationshipsRelationships

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.