2019年六月19日星期三

Office 365开发人员提示–与Microsoft Graph和其他API一起有效地工作

I’最近在各种会议上发表有关扩展Office 365的关键技能的演讲–如今,有效的架构师或开发人员需要在工具箱中拥有的东西。显然,考虑到毕竟,使用Microsoft Graph的能力必须在此列表中处于较高位置,“Office 365的API”. It’拥有一种(主要是!)一致的方式来与Teams,SharePoint,邮件,日历,Planner,OneDrive文件和许多其他功能一起工作非常好,但是在各种身份验证选项和编码样式之间,’有很多要知道的。

我发现的一件事是,开发人员可能对Graph还不够有效–部分原因是最近发生了一些变化,部分原因是某些开发人员仅使用SharePoint REST / CSOM API和其他特定于服务的API才进入Graph。

所以我在这里的关键信息是:

  • Microsoft提供的Postman集合可以帮助您回答有关Graph的问题,并将调用集成到您的代码中
  • SDK比您有更多帮助’d在您的代码中期望–以TypeScript中的类型为例
为什么这些事情很重要?

提示1-使用Postman集合代替Graph Explorer


Graph Explorer (GE) is 大 for developers to start seeing some calls that can be made to the Graph and what kind of data comes back. If you’re new to the Graph, check it out 在 //developer.microsoft.com/en-us/graph/graph-explorer. However, for intermediate and advanced developers, I recommend using Postman over Graph Explorer. Here’s why:

图资源管理器的缺点
GE的一个缺点是,即使您可以登录帐户并因此与自己的Office 365租户一起使用, 这仍然不是您的代码将要做的事情。调用代码总是需要Azure AD应用程序注册,GE不会使用您的应用程序注册–表示使用了不同的权限。所以’从Graph Explorer移到代码时,通常会遇到问题,通常与在应用程序注册中没有允许的正确权限范围有关。使用Postman可以使用您的应用程序注册表,因此’与您的代码完全相同。

使Postman具备Graph强大功能的原因是,Microsoft已针对所有当前Graph方法发布了Postman集合。–包括Beta版。您可以将它们导入Postman,然后’然后,将看到每种方法的项目,分为两个文件夹,分别用于仅应用程序调用和代表用户的调用:

这是 为了发现!现在,每当我想知道图表是否允许我获取某些东西时,我无需点击浏览文档页面,而是来到这里开始扩展文件夹:
我看到了所有Graph工作负载以及可以检索哪些数据 非常 确实很快。 Postman和Graph集合的入门过程涉及一点点-概述于 Github存储库,您可以在其中获得Microsoft的Postman Graph集合,但我认为观看某人的整个流程会有所帮助,因此我制作了一段带字幕的视频:


该过程首先获取我将使用的AAD应用程序注册的详细信息,因此,如果您还没有一个注册,则应创建一个(定义了适当的权限范围)。总体而言,该过程是:
  • 导入收藏集
  • 配置各种邮递员变量
  • 获取仅应用程序调用和“代表用户”调用的访问令牌,并将其存储在其他Postman变量中
  • 享受您对Graph的新快速访问!您可以开始执行调用,然后看到数据返回

It's fairly straightforward to integrate the call into your code, and you won't have 任何 security/permission issues because you've already tested the same thing your code will do.

更新-实际上,我现在知道杰里米也有一个视频。看到 //www.youtube.com/watch?v=4tg-OBdv_8o 为了那个。

太好了-我们现在可以在Graph中查看所有URL端点,它们期望的数据以及返回的数据。但是,一旦编写代码,我们如何确保我们与Graph有效合作?

提示2-确保您使用的是TypeScript类型


对于我们许多人来说,我们将根据Graph进行编码的地方将是SPFx或其他TypeScript代码-甚至可能是基于node.js的Azure函数。这里要避免的关键是使用“any” in TypeScript –我们可以做得更好’另一个第三方API或Graph本身。它’API通常会返回相当复杂的JSON结构,并且可以通过确保使用代表数据的类型(接口或类)进行类型检查来避免很多编码错误。此外,对这些数据结构具有自动完成功能可使编码过程更快,更准确。

在TypeScript中使用图形

在SPFx中使用图形时,要注意的第一件事是您的项目不会自动添加图形类型(例如,当Yeoman生成器创建文件时)–您必须安装一个单独的npm软件包。为此,请运行以下命令之一:
  • npm install @ microsoft / microsoft-graph-types --save-dev
  • npm安装@ microsoft / microsoft-graph-types-beta --save-dev
是的,即使您愿意,Microsoft也请提供类型’重新处理Beta Graph端点。对于大多数生产方案,您’但是,将使用第一个选项(并保持释放端点)。安装类型之后,可以使用以下命令将它们导入到SPFx类中:

从'@ microsoft / microsoft-graph-types'导入*作为MicrosoftGraph;

It’最好仅导入您要’实际使用而不是*,但这需要一些挖掘(以找到模块名称)。您’但是,使用较小的捆绑包尺寸会得到奖励。 Either way, once you’已经导入了类型,您可以在代码中开始使用它们–这改变了根本没有零支持的情况:
..键入时具有完全自动完成功能:
万岁!现在事情变得容易得多。

在没有这种支持的情况下,请尽可能避免编写代码!但是,如果您使用的不是图谱的API,该怎么办?

在TypeScript中使用第三方API

在这种情况下,要做的第一件事是确定供应商是否提供TypeScript类型(通常以npm软件包或类似的形式)。如果是这样,只需安装它,您就可以获得支持。如果没有,我喜欢使用Postman获取返回的JSON,然后使用Visual Studio Code扩展,例如 快速类型 根据该JSON为我自动生成类型。那么你’d在Postman中调用API,然后将返回的JSON复制到剪贴板。

In the example below, I'm using the Here Maps API. I set up the call in Postman by pasting in the URL endpoint to use, and setting up 任何 authentication. I hit the send button, and then copy the returned JSON (in the lower pane) to my clipboard):
在Visual Studio代码中,我创建了一个文件来保存API的接口类型,然后在命令面板中找到QuickType“将JS​​ON作为代码粘贴”选项:
我提供了顶级类型的名称:
..然后QuickType生成映射到JSON的类型结构。我可能想重命名某些类型,但是从本质上讲,我得到了结构中所有内容的接口:

太好了-这为我节省了很多交叉引用和类型输入,现在我可以在调用代码中使用这些接口,并进行类型检查和自动完成。

概要


无论是Graph还是第三方API,您都应始终根据定义的TypeScript接口进行编码。对于Graph,应通过安装Microsoft的“ microsoft-graph-types” npm软件包来使用Microsoft提供的类型。对于第三方API,如果未提供任何类型,则可以借助QuickType之类的帮助轻松生成自己的类型。

无论您做什么,Postman都是一个非常有用的工具。就Graph而言,它的使用可解决Graph Explorer无法以与代码相同的权限执行的问题,因此它与第3方API一样有价值。

祝您编码愉快!

2019年六月12日星期三

快速提示-按流中的日期筛选SharePoint项目

关于在Microsoft Flow中处理日期的快速帖子,因为我知道我将再次需要它,而且当我看时并没有立即发现任何东西。

当使用诸如“ SharePoint获取项目”之类的流程操作时,通常情况下是要按日期/时间字段筛选项目。通常,您想获取比某个时间戳更旧(或更新)的项目-也许要删除/存档/对其采取其他操作。

最简单的方法是使用 getPastTime 功能,以确保您以正确的方式格式化它。可以在“获取项目”的“过滤查询”属性中使用如下子句:

格式DateTime(getPastTime(1,'Month'),'yyyy-MM-dd')

请注意,此格式旨在与SharePoint中配置为“仅日期”格式的日期/时间字段一起使用:

对于包含时间的日期,您可能需要将formatDateTime与其他格式一起使用(对不起,我没有对此进行测试)。

有关使用getPastTime和类似功能的注意事项


“ getPastTime”方法的签名为:

getPastTime(<interval>, <timeunit>, <format>?)

“ timeUnit”的可能值列表包括:

“第二”,“分钟”,“小时”,“日”,“周”,“月”,“年”

如您所料,还有一个对应的函数称为 getFutureTime()。要在“获取项目”操作中使用其中之一,请提供OData格式的过滤查询,该查询使用日期字段的内部名称-类似于:

MyDateFieldInternalName lt 格式DateTime(getPastTime(1,'Month'),'yyyy-MM-dd')

例如,这将仅过滤一个月以上的项目。在Flow设计器中,应如下所示:



希望这是有用的。愿您所有的流程按时执行,并且没有错误!