Outlook 日历 API 概述Outlook calendar API overview

Outlook 日历是 Microsoft 365 中 Outlook 邮件中心的一部分,它还允许您管理电子邮件和联系人、查找组织中用户的相关信息、启动在线对话、共享文件以及在组中进行协作。Outlook calendar is part of the Outlook messaging hub in Microsoft 365 that also lets you manage emails and contacts, find information about users in an organization, initiate online conversations, share files, and collaborate in groups.

为什么与 Outlook 日历集成?Why integrate with Outlook calendar?

Outlook 日历及其 API 的丰富功能带来了许多应用机会。The rich features of Outlook calendar and its API open up many app opportunities. 以下部分列出了其中的一些机会。The following sections list a few of them.

覆盖数以亿计的客户并构建丰富的应用场景Reach hundreds of millions of customers and build rich scenarios

数以百万计的客户使用 Outlook 日历作为集成中心的一部分,他们可以借此有效地沟通和完成任务。Many millions of customers use Outlook calendar as part of an integrated hub that lets them effectively communicate and get things done. 他们可以设置会议、管理电子邮件、查找有关联系人和其他用户的信息,并可在一个位置启动对话或在线会议,比如 Web、移动或桌面设备。They can set up meetings, manage emails, find information about contacts and other users, and initiate conversations or online meetings all in one place, be it on the web, mobile, or desktop. Microsoft Graph 不仅可将应用连接到日历、邮件以及这些客户的联系人数据,还可使应用与 Microsoft 365 的最佳功能进行集成,并支持各种各样的应用场景,以提高工作效率和协作。Microsoft Graph not only connects apps to the calendar, mail, and contacts data of these customers, it enables apps to integrate with the best of Microsoft 365 and support a wide range of scenarios that enhance productivity and collaboration.

Outlook 日历 API 中的大多数功能适用于个人 Microsoft 帐户和工作或学校帐户中的日历。Most features in the Outlook calendar API apply to calendars in personal Microsoft accounts and work or school accounts.

** 表示仅适用于工作或学校帐户中的 Outlook 日历的专用功能。** Denotes features below that are specifically applicable to Outlook calendars in only work or school accounts.

自动化约会组织和日历功能Automate appointment organization and calendaring

客户希望 Outlook 帮助他们合理安排用于工作、家庭和个人活动的时间。Customers like how Outlook lets them organize their time for work, family, and personal activities. Microsoft Graph REST API 与客户体验保持密切对等,以便应用可以自然地创建、管理和响应事件:Microsoft Graph REST API keeps close parity with the customer experience, letting apps create, manage, and respond to events just as naturally:

  • 在 Outlook 中,客户可以针对工作、家庭或其他目的创建单个日历,并在日历组中加以组织。In Outlook, customers can create individual calendars for work, family, and other purposes, and organize them in calendar groups. 他们可以启用免费的生日节假日日历,提醒他们联系人的生日和本地假日。They can turn on the free Birthdays and Holiday calendar to remind them of contacts' birthdays and local holidays. 也可以添加匹配其兴趣的日历,如有关运动队和电视节目的日历。They can add calendars that match their interests, such as calendars for sport teams and TV programs. 客户可以选择和叠加日历,并在同一个视图中查看他们的事件。Customers can select and overlay calendars, and see their events in the same view. 在日历 API 中,应用可以按照类似的方式组织日历组中的日历,然后就像与用户邮箱中的任何其他日历一样与感兴趣的日历进行交互。Through the calendar API, your app can similarly organize calendars in calendar groups, and interact with interesting calendars just like any other calendar in the user's mailbox.

  • Outlook 客户可通过一致的方式将类别应用到事件、邮件、联系人、任务和组文章中来加强组织和发现。Outlook customers can apply categories to events, messages, contacts, tasks, and group posts in a consistent way to enhance organization and discovery. 使用日历 API,你可以访问和定义用户的主类别列表,从而开发其他创造性的应用场景。The calendar API lets you access and define a user's master list of categories, which opens up additional creative scenarios. 例如,体育俱乐部可以组织一场体育赛事,并提供一款应用,将每一项运动的电子邮件和事件按器自己的颜色类别区分开来。For example, an athletic club can organize a sports tournament and offer an app that differentiates emails and events for each sport with their own color category. 对于诸如不可预见的时间表变化等最新新闻,这款应用还可以设置这些事件和电子邮件的重要性属性来提醒用户。For last-minute news such as unforeseen timetable changes, the app can also set the importance property of those events and emails to alert customers.

  • 在日历文件夹中,可以创建更新单个实例事件,或安排和维护定期事件In a calendar folder, you can create and update single instance events, or schedule and maintain recurring events. 你可以让客户使用关联的事件导航属性来响应会议请求,以及推迟直接关闭提醒You can let your customers respond to meeting requests, and snooze or dismiss reminders using the associated event navigation property.

帮助客户保持同步并浏览他们的日期Help customers stay synchronized and navigate their day

日历 API 可帮助客户浏览他们的日期并提高效率:The calendar API helps customers navigate their day and enhance productivity:

增强协作Enhance collaboration

  • 在 Outlook 中,客户可以与他人共享日历并授予读取、写入或删除日历内容的权限。In Outlook, customers can share calendars with one another and give permissions to read, write, or delete calendar contents. 或者,他们可以委派一个日历,让另一个客户代表他们响应会议请求。Or, they can delegate a calendar to let another customer respond to meeting requests on their behalf. 通过编程方式,虽然无法代表用户启动共享或委派操作,但可以使用一组属性来验证共享状态并启用有关共享或委派日历的应用场景:canEditcanSharecanViewPrivateItemsisSharedisSharedWithMeProgrammatically, while you cannot initiate a share or delegate action on behalf of a user, you can use a set of properties to verify the sharing status and enable scenarios around shared or delegated calendars: canEdit, canShare, canViewPrivateItems, isShared, and isSharedWithMe.
  • 日历 API 使你能够获得已登录用户或将其日历共享或委派给已登录用户的用户的日历项目。The calendar API lets you get calendar items of the signed-in user, or users who have shared or delegated their calendars to the signed-in user. 例如,如果 Garth 与 John 共享日历,或者如果 Garth 向 John 委派了访问权限,则来自 John 的委派权限将授予你对 Garth 共享日历和内容的读取访问权限。For example, if Garth has shared a calendar with John, or if Garth has delegated access to John, then delegated permissions from John would give you read access to Garth's shared calendar and contents as well.
  • Microsoft 365 组使组成员可以轻松协作并在 Outlook 中直接访问组对话和日历。Microsoft 365 groups make it convenient for group members to collaborate and access group conversations and calendars right in Outlook. 除了组日历和用户日历之间的一些细微差异外,通过日历 API 可像与用户日历那样与组日历进行交互。Aside from a few minor differences between group calendars and user calendars, the calendar API lets you interact with group calendars just like user calendars. 请参阅日历资源了解详细信息**See the calendar resource for more information**.

智能日程安排Schedule smart

Outlook 和日历 API 提供了很多智能便利的功能来安排事件:Outlook and the calendar API offer many smart conveniences to schedule events:

  • 在 Outlook 日历应用设置中,客户可以启用在电子邮件中自动添加事件,如航班、酒店或就餐预订,以及开具发票等。Through Outlook calendar app settings, customers can enable automatic adding of events from emails, such as flight, hotel, or dining reservations, and billing invoices. 添加后,即可像用户邮箱中的任何其他事件那样与这些事件交互,并借此 Outlook 功能生成创造性应用场景。Once added, you can interact with these events just like any other event objects in the user's mailbox, and build creative scenarios upon this Outlook capability.
  • 在 Outlook 中,预订会议室就像添加事件与会者那样简单。In Outlook, booking a meeting room is as straight-forward as adding an attendee to the event. 日历 API 将会议室表示为 emailAddress 对象。The calendar API represents a meeting room as an emailAddress object. 你可以获取聊天室并获取租户中可用的会议室列表You can get rooms and get room lists that are available in a tenant. 若要安排在特定会议室召开会议,请将它分配到 eventlocation 属性。**To organize a meeting in a specific room, assign it to the location property of the event.**
  • 查找用户和资源在特定时间段内的忙/闲信息You can look up the free/busy information for users and resources for a specific time period. 然后,可以将此类数据应用于各种方案,包括资源计划和事件日程安排。**You can then use this data to apply to different scenarios including resource planning and event scheduling.**
  • 如果方案涉及安排在最佳时间召开会议,不妨使用 findMeetingTimes 标识可召开会议的可能时间或地点If your scenario involves scheduling meetings at an optimal time, you can consider using findMeetingTimes to identify possible times or locations to meet. findMeetingTimes 函数会考虑与会者的忙/闲状态,以及所提供的任何首选会议室、时间和其他限制。The findMeetingTimes function considers the free/busy status of the attendees, and any preferred rooms, time, and other constraints you provide. 如果首次尝试未返回常见的会议时间,请检查原因,调整条件并再次调用 findMeetingTimes**If the first try doesn't return a common meeting time, check the reason, adjust your criteria and call findMeetingTimes again.**

跨多个地点和时区的电话会议Teleconference across multiple locations and time zones

在全球化背景下,当今的商务会议通常涉及来自不同地点和时区的与会者。With globalization, today's business meetings often involve attendees participating from different locations and time zones. 下面介绍了如何使用日历 API 来管理此类会议:Here's how you can use the calendar API to manage such meetings:

  • 如 Outlook 中的一个示例所示,客户可以组织一场会议,并包括从西雅图会议室、巴黎咖啡店和中国家庭办公室加入的与会者。As an example in Outlook, customers can organize a meeting and include attendees joining from a conference room in Seattle, a coffee shop in Paris, and a home office in China. 通过编程方式,事件 locations 属性(location 对象集合)可反映每个 locationdisplayNamelocationType 中此级别的详细信息。Programmatically, the event locations property, which is a collection of location objects, can reflect this level of details in displayName and locationType for each location. 请参阅示例See an example.
  • Outlook 为客户提供了组织事件和针对每个事件的开始和结束时间指定一个时区的灵活性。Outlook gives customers the flexibility to organize events and specify a time zone for each of the start and end times of an event. 为了支持这种灵活性,默认情况下,日历 API 会以 UTC 格式返回事件开始结束时间,并提供 originalStartTimeZoneoriginalEndTimeZone 属性,以记录创建事件时使用的时区。To support this flexibility, by default, the calendar API returns the start and end times of an event in UTC, and provides the originalStartTimeZone and originalEndTimeZone properties to note the time zones used when the event was created.
  • 或者,可以指定 Prefer: outlook.timezone="{time zone name}" 标头,以便 GET 事件操作返回指定时区的开始结束时间。Alternatively, you can specify the Prefer: outlook.timezone="{time zone name}" header so that a GET event operation returns start and end in the time zone you specify. 时区名称可以是 Windows 支持的任何名称,也可以是此列表上的这些名称。The time zone name can be any of those supported by Windows, as well as those on this list. 请参阅使用中的 Prefer 标头示例See an example of the Prefer header in use.
  • 支持联机会议提供程序的组织(例如 Microsoft Teams 和 Skype)可以设置 Outlook 日历以使用这些提供程序。Organizations that support online meeting providers, such as Microsoft Teams and Skype, can set up Outlook calendars to use these providers. 可方便地组织或以在线会议的形式参加这些日历中的事件You can conveniently organize or attend events in these calendars as online meetings.

使用位置感知生成应用程序并提供智能上下文Build apps with location awareness and provide intelligent context

使用位置 API帮助用户导航到某个位置,或根据用户的位置提供智能解决方案。Use the places API to help users navigate to a place, or provide an intelligent solution based on the user's location. 下面是一些示例方案:The following are some example scenarios:

  • 在日历事件中包含地点详细信息,以帮助用户浏览当天事件并提高工作效率。**Incorporate place details in calendar events to help users navigate their day and enhance productivity.**
  • 餐饮应用程序可以使用位置 API 来协助场地导航和设置。**Catering applications can use the places API to assist venue navigation and set up.**
  • 自动将会前详细信息通过电子邮件发送给与会者,并提供有关如何到达会议室的地图。**Automate emailing pre-meeting details to attendees and include a map on how to get to a room.**
  • 设置接收机器人助理,以提供有关建筑物中的特定房间的信息。**Set up reception bot assistants to provide information about specific rooms in a building.**

根据你的应用方案,你可以在 Outlook 上下文中使用位置 API,或独立于 Outlook 进行使用。Depending on your app scenario, you can use the places API within the context of Outlook, or independent of Outlook.

利用 Microsoft Graph 的社交智能以及其他开发者的便利性Take advantage of social intelligence and other developer conveniences in Microsoft Graph

使用 Microsoft Graph 中的人员 API 连接到人员数据,这基于用户的通信和协作模式以及业务关系。Use the people API in Microsoft Graph to connect to people data which is based on a user's communication and collaboration patterns, and business relationships. 你可以实现诸如人员选取器等控件,并在代表用户组织会议时建议与用户相关的人员。You can implement controls such as a people picker, and suggest persons relevant to the user when organizing meetings on the user's behalf.

节省在外部数据存储中存储和管理应用数据的开销。Save overhead in storing and managing app data in external data stores. 使用 Microsoft Graph,可以在各个资源实例中将自定义应用数据存储为开放扩展With Microsoft Graph, you can store custom app data as open extensions in individual resource instances. 如果需要键入数据,或者希望能够共享类型化架构,可以将自定义应用数据存储在架构扩展中。If you require the data to be typed, or would like to be able to share the typed schema, you can store custom app data in schema extensions.

数据在什么位置?Where is the data?

Microsoft Graph API 支持访问用户_主_邮箱和共享邮箱中的数据。The Microsoft Graph API supports accessing data in users' primary mailboxes and in shared mailboxes. 数据可以是日历、邮件或个人联系人存储在 Exchange Online 上的云中的邮箱中,也可以是 Microsoft 365 的一部分,也可以是在混合部署中的本地 exchange 上。The data can be calendar, mail, or personal contacts stored in a mailbox in the cloud on Exchange Online as part of Microsoft 365, or on Exchange on-premises in a hybrid deployment.

此 API _不_支持访问就地存档邮箱(不在 Exchange OnlineExchange Server 上)。The API does not support accessing in-place archive mailboxes, not on Exchange Online nor on Exchange Server.

API 参考API reference

在查找此服务的 API 参考?Looking for the API reference for this service?

后续步骤Next steps