在 Outlook 中共享或委派日历

在 Outlook 中,日历所有者可与其他用户共享日历。 所有者可以指定非私人活动中的哪些信息是可供查看的,并且可向同一组织中的用户授予对日历的写入访问权限。

所有者还可以委派其他用户来管理所有者主要日历中的会议。 代理人是共享收件人,他们可以在 中查看所有信息,并且对非私人事件具有写入权限。 他们还会收到会议请求和响应,并代表所有者响应会议请求。 此外,所有者可以向委托人授予在日历上查看所有者的私人活动的显式权限。

在日历共享或委派生效之前,所有者向共享收件人发送或委托邀请,共享收件人或代理人接受邀请,或者显式添加共享日历或委派日历以供访问。 可在 Outlook 客户端中进行邀请和添加共享或委派日历。

在 Outlook 中设置共享或委派后,应用可使用 Microsoft Graph API 管理共享和委派。

本文的其余部分基于以下示例方案:

  • Alex Wilber 已将 Megan Bowen 委派到其主要日历,并且还允许 Megan 查看该日历中的私人活动。
  • Alex 与 Adele Vance 和 Megan Bowen 共享了一个“儿童派对”日历,并向 Adele 和 Megan 授予了read权限,允许他们查看“儿童派对”日历上的非私人活动的所有详细信息,以及私人活动的忙/闲状态。

本文介绍如何使用共享或委派日历以编程方式执行以下任务:

应用还可以使用通用版 API 执行以下操作:

注意

除日历属性 isSharedisSharedWithMe 外,该主题中描述的日历共享和委托的属性和 API 当前在 v1.0 终结点中可用。 这两个属性仅在 beta 终结点中公开。

获取有关共享收件人和代理人的日历信息,并更新个人权限

本节内容:

每个日历都与 calendarPermission 对象的集合相关联,每个对象描述共享收件人或代理人以及日历所有者已设置的关联权限。 calendarRoleType 枚举定义了 Microsoft Graph 支持的权限范围:

  • none 此值仅适用于 My Organization 对日历没有任何权限的用户。 它不适用于单个用户,因为只有具有权限的用户才与日历的 calendarPermission 对象相关联。
  • freeBusyRead 共享收件人可以查看所有者的忙/闲状态,但不能查看日历上的其他详细信息。
  • limitedRead 共享收件人可以查看所有者的忙/闲状态,以及日历上非私人事件的标题和位置。
  • read 共享收件人可以在私人事件中查看所有者的忙/闲状态,以及日历上非私人事件的所有详细信息。
  • write 共享收件人可以在私人事件中查看所有者的忙/闲状态,并可以查看所有详细信息和编辑 (日历上创建、更新或删除) 非私人事件。
  • delegateWithoutPrivateEventAccess 委托人可以查看所有者在私人活动中的忙/闲状态,并且对日历上的非私人活动具有write访问权限。
  • delegateWithPrivateEventAccess 委托人可以查看所有者的私人活动和非私人活动的详细信息,并且对日历上的所有活动都具有write访问权限。

用户的主要日历始终与“我的组织”共享,它代表与所有者位于同一组织中的用户。 默认情况下,他们可以在该日历上读取所有者的忙/闲状态,并且具有freeBusyRead权限。

日历所有者:获取共享或委派信息及权限

此示例演示在 Alex 或管理员同意的情况下,如何获取与 Alex 的主要日历关联的 calendarPermission 对象。 请求将返回两个此类权限对象:

  • 第一个 calendarPermission 对象已分配给委托人 Megan,并且具有下列属性值:

    • isRemovable 设置为 true,为 Alex 提供了取消委派的选项。
    • isInsideOrganization 为 true,因为只有同一组织中的用户才能成为委托人。
    • Megan 的 role 是由 Alex 设置的 delegateWithPrivateEventAccess
    • allowedRoles 包括支持委派的角色类型 delegateWithoutPrivateEventAccessdelegateWithPrivateEventAccess
    • emailAddress 指定 Megan。
  • 第二个 calendarPermission 对象是分配给“我的组织”的默认对象,并且具有下列属性值:

    • isRemovable 设置为 false,因为主要日历始终与所有者的组织共享。
    • isInsideOrganization 为 true。
    • rolefreeBusyRead,即“我的组织”的默认设置。
    • emailAddressname 子属性指定为“我的组织”;“我的组织”的 address 默认为 null。

Microsoft Graph 权限

对此操作视情况使用权限最低的委派或应用程序权限,Calendars.Read。 有关详细信息,请参阅日历权限

GET https://graph.microsoft.com/beta/users/AlexW@contoso.com/calendar/calendarPermissions
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('64339082-ed84-4b0b-b4ab-004ae54f3747')/calendar/calendarPermissions",
    "value": [
        {
            "id": "L289RXhjaGFuZ2VMYWJTWVnYW5C",
            "isRemovable": true,
            "isInsideOrganization": true,
            "role": "delegateWithPrivateEventAccess",
            "allowedRoles": [
                "freeBusyRead",
                "limitedRead",
                "read",
                "write",
                "delegateWithoutPrivateEventAccess",
                "delegateWithPrivateEventAccess"
            ],
            "emailAddress": {
                "name": "Megan Bowen",
                "address": "MeganB@contoso.com"
            }
        },
        {
            "id": "RGVmYXVsdA==",
            "isRemovable": false,
            "isInsideOrganization": true,
            "role": "freeBusyRead",
            "allowedRoles": [
                "none",
                "freeBusyRead",
                "limitedRead",
                "read",
                "write"
            ],
            "emailAddress": {
                "name": "My Organization"
            }
        }
    ]
}

日历所有者:更新日历上现有共享收件人或代理人的权限

在 Alex 或管理员的同意下,你可以更新分配给现有共享收件人或代理人 (由 角色 属性) 指定的权限,前提是新权限受最初为该日历的共享收件人或代理人设置的 allowedRoles 的支持。

除了 角色 属性之外,不能更新现有共享收件人或代理人的其他属性。 更改 emailAddress 属性值需要删除共享收件人或代理人,并再次设置 calendarPermission 的新实例。

本部分中的示例更新 角色 属性,将现有共享收件人 Adele 的权限从 read 更改为 write 自定义日历“儿童派对”。

Microsoft Graph 权限

对此操作视情况使用权限最低的委派或应用程序权限,Calendars.ReadWrite。 有关详细信息,请参阅日历权限

PATCH https://graph.microsoft.com/beta/users/AlexW@contoso.com/calendars/AAMkADAwAABf02bAAAA=/calendarPermissions/L289RXhjaGFuZ2VMYWJQWRlbGVW
Content-type: application/json

{
  "role": "write"
}
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('64339082-ed84-4b0b-b4ab-004ae54f3747')/calendars('AAMkADAwAABf02bAAAA%3D')/calendarPermissions/$entity",
    "id": "L289RXhjaGFuZ2VMYWJQWRlbGVW",
    "isRemovable": true,
    "isInsideOrganization": true,
    "role": "write",
    "allowedRoles": [
        "freeBusyRead",
        "limitedRead",
        "read",
        "write"
    ],
    "emailAddress": {
        "name": "Adele Vance",
        "address": "AdeleV@contoso.com"
    }
}

获取共享或委托日历的属性

本节内容:

在本示例中,Alex 委派了他的主要日历,并向委托人 Megan Bowen 授予了查看标记为“私人”的日历项目的权限。 此部分显示委派日历的属性,首先从所有者 Alex 的角度出发并征得其同意,然后从委托人 Megan 的角度出发并征得其同意。 来自管理员的同意也适用于每种情况。

日历所有者:获取共享或委托日历的属性

此部分的示例从所有者 Alex 的角度获取主要日历的属性。

注意以下代表 Alex 的属性:

  • canShare 为 true,因为 Alex 是所有者。
  • canViewPrivateItems 为 true,因为 Alex 是所有者。
  • isShared 设置为 true,因为 Alex 为此日历设置了委托人。
  • 对于日历所有者,isSharedWithMe 始终为 false。
  • owner 显示 Alex 为所有者。

Microsoft Graph 权限

对此操作视情况使用权限最低的委派或应用程序权限,Calendars.Read。 有关详细信息,请参阅日历权限

GET https://graph.microsoft.com/beta/users/AlexW@contoso.com/calendar
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('64339082-ed84-4b0b-b4ab-004ae54f3747')/calendar/$entity",
    "id": "AQMkADAw7QAAAJfygAAAA==",
    "name": "Calendar",
    "color": "auto",
    "hexColor": "",
    "changeKey": "NEXywgsVrkeNsFsyVyRrtAAAAAACOg==",
    "canShare": true,
    "canViewPrivateItems": true,
    "isShared": true,
    "isSharedWithMe": false,
    "canEdit": true,
    "allowedOnlineMeetingProviders": [
        "teamsForBusiness"
    ],
    "defaultOnlineMeetingProvider": "teamsForBusiness",
    "isTallyingResponses": true,
    "isRemovable": false,
    "owner": {
        "name": "Alex Wilber",
        "address": "AlexW@contoso.com"
    }
}

共享收件人或代理人:获取共享或委派日历的属性

此部分的示例从委托人 Megan 的角度获取同一日历的属性。

注意下列属性:

  • 默认情况下,日历的 name 是所有者的显示名称。 在本例中,它是“Alex Wilber”,因为这是 Alex 委派给 Megan 的日历。
  • canShare 为 false,因为 Megan 不是此日历的所有者。
  • 对于由 Alex 设置的委托人 Megan,canViewPrivateItems 为 true。 对于不是委托人的共享者,此属性始终为 false。
  • isShared 为 false。 此属性仅向日历所有者指示日历是共享日历还是委派日历。
  • isSharedWithMe 属性为 true,因为 Megan 是委托人。
  • canEdit 是 true,因为包括 Megan 在内的委托人具有写入访问权限。
  • owner 设置为 Alex。

注意

共享者或委托人只能自定义共享/委派日历的 name 属性。 更新仅对他们自己可见;日历所有者无法查看此类日历名称更改。

Microsoft Graph 权限

对此操作视情况使用权限最低的委派权限 Calendars.Read.Shared 或应用程序权限 Calendars.Read。 有关详细信息,请参阅日历权限

GET https://graph.microsoft.com/beta/users/meganb@contoso.com/calendars/AAMkADlAABhbftjAAA=
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('meganb%40contoso.com')/calendars/$entity",
    "id": "AAMkADlAABhbftjAAA=",
    "name": "Alex Wilber",
    "color": "auto",
    "hexColor": "",
    "changeKey": "E6LznKWmX0KTsAD9qRJjeAAAYWo3EQ==",
    "canShare": false,
    "canViewPrivateItems": true,
    "isShared": false,
    "isSharedWithMe": true,
    "canEdit": true,
    "allowedOnlineMeetingProviders": [
        "teamsForBusiness"
    ],
    "defaultOnlineMeetingProvider": "teamsForBusiness",
    "isTallyingResponses": true,
    "isRemovable": true,
    "owner": {
        "name": "Alex Wilber",
        "address": "AlexW@contoso.com"
    }
}

获取或设置邮箱设置以接收会议请求和响应

本节内容:

根据日历所有者首选的委派级别,所有者可以指定接收会议请求和响应的人员,以管理日历上的会议。

可通过编程方式获取或设置日历所有者的 mailboxSettingsdelegateMeetingMessageDeliveryOptions 属性,以指定 Outlook 应将 eventMessageRequesteventMessageResponse 实例定向到的人员:

  • sendToDelegateOnly

    Outlook 仅将 eventMessageRequesteventMessageResponse 实例定向到委托人。 这是默认设置。 所有者可以通过委派日历中的相应活动来查看对会议的响应或对邀请的响应。

  • sendToDelegateAndInformationToPrincipal

    Outlook 将 eventMessageRequesteventMessageResponse 实例定向到委托人和日历所有者。 只有委托人才能看到接受和拒绝会议请求的选项。发送给所有者的通知将以一般电子邮件的形式显示。 所有者仍可以通过在委派日历中打开活动并做出响应来响应会议。

  • sendToDelegateAndPrincipal

    Outlook 将 eventMessageRequesteventMessageResponse 实例定向到委托人和日历所有者,他们都可以响应会议请求。

这是邮箱范围的设置,因此相同的设置适用于邮箱所有者的所有委托人。

获取用户邮箱的委派传递设置

此部分的示例将获取日历所有者的 mailboxSettings,该所有者仅允许 Outlook 将会议请求和响应定向到日历委托人;即 delegateMeetingMessageDeliveryOptions 设置为 sendToDelegateOnly

Microsoft Graph 权限

对此操作视情况使用权限最低的委派或应用程序权限,MailboxSettings.Read。 有关邮箱权限的详细信息,请参阅邮件权限

GET https://graph.microsoft.com/beta/users/AlexW@contoso.com/mailboxsettings
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('64339082-ed84-4b0b-b4ab-004ae54f3747')/mailboxSettings",
    "archiveFolder": "AQMkADAwAGVQAAAKfowAAAA==",
    "timeZone": "Pacific Standard Time",
    "delegateMeetingMessageDeliveryOptions": "sendToDelegateOnly",
    "dateFormat": "M/d/yyyy",
    "timeFormat": "h:mm tt",
    "automaticRepliesSetting": {
        "status": "disabled",
        "externalAudience": "all",
        "internalReplyMessage": "",
        "externalReplyMessage": "",
        "scheduledStartDateTime": {
            "dateTime": "2019-12-24T05:00:00.0000000",
            "timeZone": "UTC"
        },
        "scheduledEndDateTime": {
            "dateTime": "2019-12-25T05:00:00.0000000",
            "timeZone": "UTC"
        }
    },
    "language": {
        "locale": "en-US",
        "displayName": "English (United States)"
    },
    "workingHours": {
        "daysOfWeek": [
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday"
        ],
        "startTime": "08:00:00.0000000",
        "endTime": "17:00:00.0000000",
        "timeZone": {
            "name": "Pacific Standard Time"
        }
    }
}

设置用户邮箱的委派传递设置

此部分的示例将 delegateMeetingMessageDeliveryOptions 属性更新为 sendToDelegateAndPrincipal,以让 Outlook 将委派日历的会议请求和响应定向到所有委托人和所有者。

Microsoft Graph 权限

对此操作视情况使用权限最低的委派或应用程序权限,MailboxSettings.ReadWrite。 有关邮箱权限的详细信息,请参阅邮件权限

PATCH https://graph.microsoft.com/beta/users/AlexW@contoso.com/mailboxsettings
Content-type: application/json

{
  "delegateMeetingMessageDeliveryOptions": "sendToDelegateAndPrincipal"
}
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('64339082-ed84-4b0b-b4ab-004ae54f3747')/mailboxSettings",
    "delegateMeetingMessageDeliveryOptions": "sendToDelegateAndPrincipal"
}

删除日历的共享者或委托人

在下面的示例中,Alex 将删除作为“儿童派对”日历共享者的 Megan。

Microsoft Graph 权限

对此操作视情况使用权限最低的委派或应用程序权限,Calendars.ReadWrite。 有关详细信息,请参阅日历权限

DELETE https://graph.microsoft.com/beta/users/AlexW@contoso.com/calendars/AAMkADAwAABf02bAAAA=/calendarPermissions/L289RXhjaGFuZ2VMYWJTWVnYW5C
HTTP/1.1 204 No Content