通过

Connect(); 2016

第 31 卷，第 12 期

Office - Microsoft Graph： 获取数据和实现智能化的网关

作者：Yina Arenas; 2016

Microsoft 的一个关键策略是：通过支持开发人员在 Microsoft 平台上构建智能的、以人为本的应用程序来“重塑工作效率”，让用户从工作和生活中获得更多收益。

我们的工作方式正在快速发展。人们似乎总是要保持连接，用户希望应用程序帮助他们完成手头的任务 - 在他们需要的确切时刻、在他们所在的地点以及相关的上下文，应用程序可以智能地利用可用的数据在人与信息之间进行有意义的连接，并且有效利用最宝贵的商品：时间。

设想有这样一个应用程序，它可以查看你的下一次会议并帮助做好准备，例如提供有用的与会者资料信息，不仅包括他们的职位，还包括他们与谁一起工作，以及他们所致力于的最新文档或项目的信息。

或者，想象有一个应用程序，不仅可以访问你的日历，还能建议下次召开团队会议的最佳时间。

如果应用程序可以基于 OneDrive 中的 Excel 文件获取最新的销售预测图表，并让你通过手机实时更新预测，会怎么样？

或者，如果应用程序可以订阅你对日历的更改，在你花费太多时间在会议上时发出提醒，以及根据与会者和你的相关程度向你可能遗漏或指派的与会者提供建议，会怎么样？

再或者，如果应用程序可以帮助你整理手机上的个人和工作信息，例如孩子们的图片应移至 OneDrive，而费用收据报表的图片应移至 OneDrive for Business，会怎么样？

Microsoft Graph 可以轻松为所有这些应用示例提供支持。

为开发人员提供前所未有的机会

在信息丰富的时代，我们知道人们都在寻求综合体验来帮助自己利用大量的数据来源，并以有意义的方式将多个接触点的信息关联起来。在这种情况下，Microsoft Graph 正是关键的推动因素，支持开发人员创建强大和个性化的基于云的应用程序，进而可以改变工作效率前景。

如果看一下开发人员可用的海量数据，将发现每月大约安排 8.5 亿个 Outlook 会议，其中超过 1 亿个是 Skype 会议。到目前为止，已使用 Office 发送了 4 万亿封电子邮件，访问了存储在 Office 365 中的数百 PB 数据。用户每天平均在 Office 中花费两到三个小时，而现在 Office 应用是移动应用，移动 Office 应用的下载量刚好超过 3.4 亿次；这两年前是不可能达到这个数字的！

Microsoft Graph： 轻松集成

创建 Microsoft Graph (graph.microsoft.com) 是为了满足用户对智能上下文体验的需求，以及为了缓解开发人员逐个集成 Microsoft 服务的痛苦。Microsoft Graph 是开发人员用于访问 Microsoft 智能云中所有数据、智能和 API 的统一网关，这包括 Exchange、SharePoint、Azure Active Directory、OneDrive、Outlook、OneNote、Planner、Excel 等。Microsoft Graph 还包括基于其智能引擎执行的机器学习计算的见解和丰富的关系。所有这些内容都可以通过同一个 REST API 终结点获得，通过单个身份验证情景将所有 Microsoft API 集中在一个 URI 命名空间中，跨所有这些 API 提供更简单的开发人员体验。

Microsoft Graph 之所以如此重要，是因为 Office 365 中的数据（组织层次结构、日历、邮箱、文件等）是组织以及人们如何完成任务的基石。同时，应用程序越容易利用所有这些数据，它们就越智能，继而为用户提供更好的体验。

如图 1 所示，Microsoft Graph 将来自多个服务的信息集中起来，并在单个请求中提供给应用程序。开发人员可以构建以用户和小组为中心的体验，从而帮助用户获得更多益处。例如，一个工作效率应用，可以提供你将与之会面的所有人员的资料和图片，并能告知这些人员的组织结构以及与他们相关的主题。数据存储在哪里并不重要；使用 Microsoft Graph，可以通过单个终结点来访问数据。

应用可以借助 Microsoft Graph 访问数字工作和数字生活数据
图 1 应用可以借助 Microsoft Graph 访问数字工作和数字生活数据

Microsoft Graph 还可用于跨服务遍历数据，以实现丰富的内容场景。例如，一个教育应用，可围绕小组模拟教室，让老师跟踪学生提交的项目文档，查看文件修改者，跟踪学生的协作和进度，以及围绕与课程相关的主题展开对话。

实现智能

Microsoft Graph 通过将智能机器学习算法与丰富的数据和用户行为相结合以找到智能见解。使用 Microsoft Graph，开发人员可以访问这些相关数据，使应用程序与上下文相关和更智能。例如，Microsoft Graph 中由 People API 提供支持的人员挑选控件，利用其模糊匹配功能，用户不必记住如何拼写一些复杂的姓氏，只需通过记住发音即可获取数据。想象一下有这样一个销售应用，可以让销售代表快速获得客户的联系信息，并在需要时立即提供。有多少次你忘记了如何拼写一个名字，然后不得不慌乱地基于其他关键字查找联系人？

Microsoft Graph 智能的另一个用处是它能够获得趋势文档。Microsoft Graph 可侦听信号和活动，例如文件上载、文件查看和修改、电子邮件会话等。然后，它使用其智能引擎计算人员与文档之间丰富的关系和推断出的见解。文件在你的圈子中流行时，Microsoft Graph 会创建一个趋势见解；此信息随后可用于强化上下文体验（例如 Office 365 中的 Delve），现在也可以作为 Microsoft Graph 中的 API 提供给开发人员。

延伸至数百万用户

Microsoft Graph 也是消费者云和商业云的统一终结点。工作与个人生产力之间的界线越来越模糊。该应用可以将个人和工作照片分类放到 OneDrive 和 OneDrive for Business，可以使用 Microsoft Graph 通过单个基本代码和单个应用注册进行编写。这意味着开发人员可以使用单一终结点和相同的代码访问位于 Outlook.com、Hotmail.com、Live.com 和 Microsoft 云其他个人帐户中的个人数据，以及位于 Office 365 和 Azure Active Directory 帐户中的工作和学校数据。因此，通过 Microsoft Graph，可以使用相同的代码与单个应用注册和单个身份验证流。

除了是消费者和商业服务的统一终结点以外，Microsoft Graph 还是主权部署的统一终结点。Microsoft 今年宣布在中国正式公开发布 Microsoft Graph。这加强了中国的 ISV 生态系统，支持多国家/地区 ISV 为中国市场开发更智能的应用。由于在其他市场中提供了更多的主权云，Microsoft Graph 也成为访问其数据的网关。

此外，Microsoft Graph 还希望消除云与本地部署之间的可编程性差距。目前在预览版中，Microsoft Graph 可以访问客户的混合部署的本地 Exchange 2016 邮箱。从开发的角度来看，代码可以不知道数据的位置，并且相同的代码可以从云中的邮箱（无论是 Office 365 邮箱还是 Outlook.com/Hotmail.com 邮箱）或本地邮箱获取数据。Microsoft Graph 负责查找数据的位置并为应用检索数据。

Microsoft Graph 是 Office 平台的核心

Microsoft Graph 改变了 IT、用户和开发人员的工作环境和工作效率。对于 IT 部门，由于图形集成和安全的数据访问，应用更易于部署和管理。对于用户，应用更加智能、丰富，与上下文更相关。对于开发人员，Microsoft Graph 通过缩短开发时间并简化与数据和智能的集成，带来了巨大的价值。

今天，创新型企业正通过 Microsoft Graph 改变工作环境和工作效率。例如，

  • Zapier： 借助 Microsoft Graph 来充分运用 Excel 数据，让用户创建强大的“zaps”或个人工作流程，以便将数据收集自动化到 Excel 中并与其他云服务集成。这种集成是 Microsoft Graph 及其 Excel REST API 之前无法实现的。
  • Smartsheet： 与 Outlook 中的 Microsoft Graph 集成，使 Outlook 用户能够在利用 OneDrive 和其他服务中的数据的同时，还能基于 Outlook 体验与 Smartsheet 中的工作表和项目进行交互。
  • SkyHigh Networks： 利用 Microsoft Graph，使安全团队能够获取敏感数据的可见性，对用户或组应用数据丢失防护策略，以及识别或警告高风险行为。
  • Hyperfish： 一个全新的初创公司，使组织能够快速轻松地自动识别和填充缺失的用户个人资料信息。它将空白的人物卡转换成丰富的卡，以加快人与人之间的联系。
  • Workday： 使用 Microsoft Graph 与 Office 365 组集成，以便当员工在组织中开始新职位时，Workday 中的所有更改都会自动反映在 Office 365 组中，员工可以立即访问所有事件、对话和文档。

API

Microsoft Graph 使用 Web 标准，使任何能够发出 HTTP 请求的设备与之进行交互。它是一个 RESTful API，遵循最近公布到 API 社区并在 bit.ly/2dzFp1a 上提供的 Microsoft REST API 准则。Microsoft REST API 准则中的许多部分都从标准化和合理化练习演变而来，用于统一现有的服务 API 及其直接终结点和模式，以便它们可以参与 Microsoft Graph。我个人撰写了第一个关于命名约定和大小写的方案，该方案已纳入到本指南中，并且 Microsoft 的 15 个合作创建 Microsoft Graph 的团队已在长时间的内部 API 讨论会中讨论了该方案。

Microsoft Graph 支持一组丰富的查询参数，例如 select、filter、expand 和 orderBy，可用于指定和控制响应中返回的数据量。Microsoft Graph 还提供不断增多的设备和服务的 SDK，因此，无论你是对 iOS、Android 或通用 Windows 平台 (UWP) 应用进行操作，创建 .NET Azure 网站，还是通过 Node.js、Python、PHP 或 Ruby 构建服务，都可以将 Microsoft Graph 数据快速整合到应用程序中。

Microsoft Graph 入门

那么如何利用 Microsoft Graph？ 首先导航到 graph.microsoft.io。这会将你转到开发人员门户，你可在该门户中找到快速开始的体验，在不到五分钟的时间内即可让你启动开发工作，而且在你选择的调用 Microsoft Graph 的平台中有一个工作应用程序。

在 Microsoft Graph 开发人员门户，还可以找到文档、完整的 API 参考、各种平台上的完整 SDK 和代码示例套件，以及 Graph Explorer。使用 Graph Explorer，可以将请求发送到 Microsoft Graph，使用个人帐户立即检查响应，无论是工作帐户、学校帐户还是模拟帐户都可以。图 2 显示了一些示例请求，其中列出了可以使用 Microsoft Graph 访问的数据类型。可以使用 API 读取、创建、更新和删除数据。可以使用 Graph Explorer 轻松尝试所有这些请求和其他请求。

图 2 Microsoft Graph 中的示例请求

操作 服务终结点
获取我的个人资料 https://graph.microsoft.com/v1.0/me
获取我的文件 https://graph.microsoft.com/v1.0/me/drive/root/children
获取我的照片 https://graph.microsoft.com/v1.0/me/photo/$value
获取我的邮件 https://graph.microsoft.com/v1.0/me/messages
获取我的日历 https://graph.microsoft.com/v1.0/me/calendar
获取我的经理 https://graph.microsoft.com/v1.0/me/manager
获取上次修改 foo.txt 文件的用户 https://graph.microsoft.com/v1.0/me/drive/root/children/foo.txt/lastModifiedByUser
获取我组织中的用户 https://graph.microsoft.com/v1.0/users
获取群组聊天 https://graph.microsoft.com/v1.0/groups/<id>/conversations
获取与我相关的人 https://graph.microsoft.com/beta/me/people
获取我的任务 https://graph.microsoft.com/beta/me/tasks
获取我的备注 https://graph.microsoft.com/beta/me/notes/notebooks
获取在我周围流行的文件 https://graph.microsoft.com/beta/me/insights/trending

 

现在我将更详细地介绍 Microsoft Graph。首先，使用 graph.microsoft.io 中的“入门”链接创建一个 ASP.NET MVC Web 应用程序，该应用程序使用 Microsoft Graph .NET SDK 以代表用户发送邮件。然后，通过额外调用 Microsoft Graph 中公开的 OneDrive API 来对其进行增强，以查询用户的最近文件。

导航到“入门”页面并与尝试体验进行交互后，请导航到页面底部，并选择 ASP.NET MVC 入口点。

下一步是按照该链接注册应用。记住复制并保存“密钥”，因为它不会再显示。完成这个过程之后，会得到一个包含项目的 .zip 包。提取文件，在 Visual Studio 中打开项目，然后构建并运行它。如果需要更新或更改注册的应用，可以在 apps.dev.microsoft.com 上完成。

这一快速入门体验会捕捉代码示例，将应用程序 ID 和密钥插入到 web.config 文件中，并使项目做好运行准备。正在运行的应用是生成的 ASP.NET 4.6 MVC Web 应用，它使用 Microsoft Graph API 连接到 Microsoft 工作或学校 (Azure Active Directory) 或个人 (Microsoft) 帐户，以便发送电子邮件。它使用 Microsoft Graph .NET SDK 处理 Microsoft Graph 返回的数据。

现在，已经启动并运行项目，接下来将添加对 OneDrive API 的调用，以便获取已登录用户最近使用的项目列表。此列表包括用户驱动器中的项目以及她可以从其他驱动器访问的项目。

第一步是修改 web.config 文件以添加 Files.Read 权限范围，使应用程序对用户的 OneDrive 进行读取访问。在 web.config 文件中，在 appSettings 元素中查找 ida:GraphScopes 密钥，并将 Files.Read 添加到值字符串。下次用户启动应用时，服务将识别新范围并动态要求用户接受：

<appSettings>
  ...
  <add key="ida.GraphScopes" value="User.Read Mail.Send Files.Read" />
</appSettings>

接下来将修改控制器。打开控制器文件夹中的 HomeController.cs；此类包含用于初始化 Microsoft Graph .NET SDK 以响应 UI 事件的操作。添加图 3 中的方法，以获取前 10 个最近的 OneDrive 项目。

图 3 获取前 10 个最近的 OneDrive 项目

[Authorize]
// Get the items that are shared with the current user.
public async Task<ActionResult> GetMyRecentItems()
{
  try
    {
      // Initialize the GraphServiceClient.
        GraphServiceClient graphClient = SDKHelper.GetAuthenticatedClient();
        // Get the recent items.
        ViewBag.RecentItems =
          await graphClient.Me.Drive.Recent().Request().Top(10).GetAsync();
        return View("Graph");
      }
      catch (ServiceException se)
      {
        if (se.Error.Message ==
          Resource.Error_AuthChallengeNeeded) return new EmptyResult();
        return RedirectToAction("Index", "Error", new { message =
          string.Format(Resource.Error_Message, Request.RawUrl,
          se.Error.Code, se.Error.Message) });
      }           
}

请注意该方法之前的 [Authorize] 语句。这是为了确保在用户尚未登录的情况下，此请求将启动登录。

最后，更新视图文件夹中的视图 Graph.cshtml 以包括将触发请求的按钮，更新 div 以呈现项目名称，以及为返回列表中的每项创建项目的用户名称。通过在文件末尾附加图 4 中的代码来执行此任务。

图 4 更新视图文件夹中的视图 Graph.cshtml

<h2>Recent OneDrive Items</h2>
@using (Html.BeginForm("GetMyRecentItems", "Home"))
{
  <div class="col-sm-12">
    <div class="form-group">
      <button class="btn btn-default">Get Recent OneDrive Items</button>
    </div>
  </div>
}
<div class="col-sm-12">
  <label for="recent-items">Recent Items</label>
  @if (ViewBag.RecentItems != null)
  {
    foreach (var item in ViewBag.RecentItems)
    {
      <div class="row">
        <div class="col-sm-4">@item.Name</div>
        <div class="col-sm-8">@item.CreatedBy.User.DisplayName</div>
      </div>
    }
  }
</div>

获得一个 ASP.NET 4.6 MVC Web 应用，它连接到 Microsoft Graph，可以由具有 Microsoft 工作或学校 (Azure Active Directory) 帐户的用户或具有个人 (Microsoft) 帐户的用户使用，以便从他们的 Outlook.com 或 Office 365 邮箱发送电子邮件并访问 OneDrive 或 OneDrive for Business 数据。这是一个简单的示例，说明使用 Microsoft Graph 从 Microsoft 云获取数据是多么的容易，无论数据是来自 Azure Active Directory、SharePoint、OneDrive、Exchange、Outlook.com、Planner、OneNote、Excel 还是其他服务，都很容易获取。

设想一下可以构建的应用程序。Microsoft 正在努力增加 Microsoft Graph 中提供的服务和功能的数量，深化其对用户活动的理解，以便得出更丰富的推断和关系，简化开发人员体验，以便可以从单个连接的 API 访问所有这些内容。

对于开发人员来说，这是一个巨大的机会，他们可以使用 Microsoft Graph 来获取所有这些数据和智能。Microsoft Graph 自 2015 年 11 月推出以来的势头足以说明了这一点。Microsoft 已经注意到下列几项数据在急剧增加：注册的应用数量、同意使用 Microsoft Graph 应用的组织数量，以及积极使用这些应用的最终用户的数量。使用 Microsoft Graph 构建的部分应用已达到数百万个活动日常用户。

总结

使用 Microsoft Graph，开发人员能够构建智能的、以人为本的应用，以便轻松地与来自所有现代工作接触点的数据进行交互。它使开发人员能够利用 Microsoft 云服务中的大量数据，构建更智能的应用并帮助人们提高工作效率。Microsoft Graph 在 Office 365 和 Azure Active Directory 中公开 API、数据和智能。Microsoft 正在勾画近期的蓝图，Microsoft 多个图形和所有 API 都将参与其中，并可通过单一的统一网关获得 Microsoft 云的强大功能。这将转化为生态系统，通过在所有垂直行业创建关联的体验来帮助重塑工作效率。它开创了这样一个未来，开发人员可以重塑医疗保健、教育、金融、法律和更多的行业；可能性是无限的。我迫不及待想看看你使用 Microsoft Graph 构建的应用。

Yina Arenas是 Microsoft 的首席项目经理，也是 Microsoft Graph 的负责人。她将 Office 和 Microsoft API 从传统和脱节的技术带到了一个全新、统一的 API 领域。Yina Arenas 和丈夫、三个充满活力的儿子住在西雅图地区，她积极领导和参与从技术方面培养、保留和支持妇女的活动。可以在 Twitter 找到她：@yina_arenas。

衷心感谢以下 Microsoft 技术专家对本文的审阅： Agnieszka Girling、Gareth Jones 和 Dan Kershaw
Agnieszka Girling、Gareth Jones 和 Dan Kershaw 是 Microsoft Graph 团队的首席项目经理，还有 Yina Arenas，他们帮助设计 API 并负责 Microsoft 最具战略性的 API 全面设计选择和技术方向。