Microsoft Graph是什么?
Microsoft Graph 是 Microsoft 365 中通往数据和智能的网关。 它提供统一的可编程模型,可用于访问 Microsoft 365、Windows 10 和企业移动性 + 安全性中的海量数据。
这句话来自微软的官网介绍,听起来很拗口,简单的说,就是微软的API。
在理解Microsoft Graph之前,需要知道Microsoft365能做什么?答案是,能做微软提供的所有在线服务。
这里,除了常见的Web开发,还包括Network,Office,AD域,安全,物联网,AI,域名等等。
整个系统,就像计算机“图论”里的一个“Graph”,把 人,机器,日历,任务,会议,文件 等连接在了一起。
这或许就是被叫做Microsoft Graph而不叫Microsoft API的原因。
2.注册自己的App
Microsoft Graph开发的第一步,就是要注册自己的App,在微软云后台里,注册App后,能够获取到2个重要的参数:
Application (client id) ID和 Directory (tenant id) ID。
Application ID是系统识别每一个应用程序,而Directory ID是租户的标识。(这2个参数非常重要,后面会说要获取Token。)
3.增加密钥
在获取Token时,还需要传递密钥,密钥可以认为是ApplicationID的密码,因为ApplicationID是固定的,而密钥则允许管理员定期修改。
点击“New Client Secret”就可以了,让系统随机生成密钥。
4.获取Token
Token令牌就像在公司里“员工证”。有了Token以后,就可以读取Microsoft Graph提供的接口了(且慢,还要授权),
下面是一个POST示意网址,用来生成Token,
https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?
client_id=11111111-1111-1111-1111-111111111111
&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query
&scope=offline_access%20user.read%20mail.read&state=12345
简单分解一下上面网址,
首先,POST网址到 https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize,然后带上client_id参数,
下面是返回示意图:
{ "token_type": "Bearer", "scope": "user.read%20Fmail.read", "expires_in": 3600, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...", "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..." }
当成功后,系统会返回一个JSON字符串,其实字符串里包含想要的Access Token令牌。
另外几个参数,expires_in 表示token有效期为3600秒,每一次调用token,系统都会返回不同的token。
但是,如果频繁调用,有可能Microsoft有次数限制,因此,在获取token后,通常要存储在本地,每次直接从本机上读取,
而不是每次都要到服务器上获取。
5.生成 Bearer token
在上面获取的token有一个token_type,也许后期会变,但是感觉变化可能性极低。什么是Bearer token?Bearer的中文翻译是持有人,其实Bearer token是什么鬼,
你也不用管那么多,反正就是“Bearer+空格+Token” 就生产了。在程序里,直接拼凑即可。
例如:
Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
这个作为Request的Header的Authorization的值。
例如,要获取公司里前5个人的列表,直接Get请求下面网址时,Microsoft Graph会先从Header里提取Authorization判断您的权限,然后返回结果。
https://graph.microsoft.com/v1.0/users?$top=5
如果使用.NET基本代码如下:
string token="Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q..."; string url="https://graph.microsoft.com/v1.0/users?$top=5"; WebRequest request = (WebRequest)HttpWebRequest.Create(url); request.Method = "Get";
request.Headers.Set("Authorization", token);
6.应用授权
默认,Token的权限非常低,他仅能读取个人信息,接下来要对API 授权,给与App更多的权限。
在 API permissions 里,点击 Add a permission,然后选择对应的权限,再点击“Grant Admin consent” 授权
7.读取Windows365里的用户日历或者会议室日历
在Microsoft Graph里,列出了大量接口,例如 List calendars - Microsoft Graph v1.0 | Microsoft Docs
在每一个接口里,都简单的表示请问方式和网址。GET表示此请求需要使用GET方式获取。POST 表示此请求需要以POST方式获取。
/me/calendars 表示请求的地址是 https://graph.microsoft.com/me/calendars
请求发出后,系统会返回JSON格式的内容,利用第三方插件,可以解析这些JSON字符串
HTTP/1.1 200 OK Content-type: application/json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#me/calendars", "value": [ { "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/calendars('AAMkAGI2TGuLAAA=')", "id": "AAMkAGI2TGuLAAA=", "name": "Calendar", "color": "auto", "changeKey": "nfZyf7VcrEKLNoU37KWlkQAAA0x0+w==", "canShare":true, "canViewPrivateItems":true, "hexColor": "", "canEdit":true, "allowedOnlineMeetingProviders": [ "teamsForBusiness" ], ] }
8.使用微软的SDK-Microsoft Graph .NET Client Library
微软提供了Java/Asp.net/Php等各种语言的SKD,对于.NET而言, https://github.com/microsoftgraph/msgraph-sdk-dotnet 是.NET的SDK
这些SDK封装了各种验证,直接提供简单的类库调用。获取Microsoft Driver只要一句代码即可。
var drive = await graphClient.Me.Drive.Request().GetAsync();
当你熟悉了上面的操作后,读取Microsoft 365 Exchange的日历,会议信息, 创建 Microsoft Team视频会议, 获取AD域里用户邮件等等都变的非常简单。