Postman 是用于构建和使用 API 的 API 平台。 Postman 简化了 API 生命周期的每个步骤并简化了协作,以便可以更快地创建更好的 API。
本文介绍如何将 Microsoft Graph 连接器 API 与 Postman 配合使用。
先决条件
- Microsoft 帐户或者工作或学校帐户。
- 访问 Microsoft 365 开发人员租户。如果没有,可以注册 Microsoft 365 开发人员计划,以获取免费的开发人员订阅。
步骤 1:分叉 Microsoft Graph Postman 集合
要使用 Postman 集合,需要将其导入到 Postman 工作区。在 Web 浏览器执行此操作。
-
登录后,转到以下 URL:
https://www.postman.com/microsoftgraph/workspace/microsoft-graph/collection/455214-085f7047-1bec-4570-9ed0-3a7253be148,然后选择 Microsoft Graph 集合。 -
选择右侧的三个点,然后选择“创建分叉”。
显示 Postman 中 Microsoft Graph 集合和创建分支选项的屏幕截图
-
在打开的对话框中,输入标签以标识您的分支。 在“工作区”下拉菜单中,选择“我的工作区”,然后选择“分支集合”。
显示 Postman 中的"分支集合"对话框和用于输入标签选项的屏幕截图,并选择"我的工作区"
-
转到“工作区” > “我的工作区”,以查看创建的分支。 可在“应用程序”下找到 Microsoft Graph 连接器文件夹。
Postman 中"我的工作区"部分的屏幕截图,其中显示了分支 Microsoft Graph 集合
步骤 2 - 下载 Postman 代理(可选 - 仅限 Postman Web 浏览器)
要在 web 浏览器中使用此 Postman 集合,请下载 Postman 桌面代理。
由于 Web 浏览器中的 CORS 限制,无法在缺少此项的情况下使用面向 Web 的 Postman:“每个 Microsoft 365 租户的最大 连接 数。”
如果你正在使用 Postman for Windows 应用,则不需要此代理。 如果打开 Postman for Windows,则会在工作区中看到此集合。
步骤 3:创建 Azure AD 应用程序
要在自己的开发人员租户中使用此集合,请创建一个 Azure Active Directory (Azure AD) 应用程序,并根据想要调用的请求向其授予合适权限。
- 转到 portal.azure.com 并使用开发者租户管理员帐户登录。
- 在 Azure 服务 下,选择“Azure Active Directory”。
- 在左侧菜单上,选择 注册。
- 在水平菜单中,单击“新建注册”。
- 将“应用名称”设置为“
Parts Inventory”。 - 将“重定向 URI”设置为“
https://oauth.pstmn.io/v1/browser-callback”。 - 选择“注册”。
- 在左侧菜单上,选择 API 权限。
- 在水平菜单上,选择“添加权限” > “Microsoft Graph” > “委派权限”。
- 开始键入
ExternalItem.ReadWrite.All,然后选择ExternalItem.ReadWrite.All。 - 选择“应用程序权限”,键入
ExternalItem,然后选择“应用程序权限”。 - 展开 ExternalItem 选项,然后选择
ExternalItem.ReadWrite.All。 - 选择 添加权限。
- 在水平菜单上,选择“授予管理员同意”,然后选择“是”。
- 在左侧的菜单中,选择“概述”。 在这里,可以获取 应用程序(客户端)ID 和 目录(租户)ID。 步骤 4 中将需要使用这些信息。
- 在左侧菜单中,选择“证书和机密”。
- 选择“新建客户端机密”,输入说明,然后选择“添加”。 复制新的客户端密码值;步骤 4 中将需要使用该密码。
应用程序现在配置了两个权限。 ExternalItem.ReadWrite.All 添加为委派权限,这是需要登录用户的权限。 应用程序可以代表用户读取/写入外部项。 ExternalItem.ReadWrite.All 添加为应用程序权限,这是不需要登录用户的权限。 应用程序可以代表自己读取/写入外部项。
步骤 4:配置身份验证
在此步骤中,请在 Postman 中设置用于检索访问令牌的环境变量。
-
选择 "Microsoft Graph" 选项卡,然后转到 "变量" 部分。
Microsoft Graph 连接器 API 选项卡和"变量"部分屏幕截图
-
在“变量”部分,使用步骤 3 中的信息提供所需信息:
- 将 租户 的当前值设置为步骤 3.15 中的目录(租户)ID 值。
- 将 客户端_id 的当前值设置为步骤 3.15 中的应用程序(客户端)ID 值。
- 将 客户端_密码 的当前值设置为步骤 3.17 中的客户端密码值。
- 将 用户名 的当前值设置为
admin@xxxxxxx.onmicrosoft.com。 - 将 密码 的当前值设置为租户管理员密码。
显示所选变量的屏幕截图
-
选择“保存” / “更新”。
步骤 5:获取身份验证令牌
由于这是你第一次通过应用程序身份验证流程运行请求,你需要获取访问令牌。 通过以下 POST 请求获取应用访问令牌:
"获取应用访问令牌"分区的屏幕截图
以下示例显示了如何获取共享密码的访问令牌:
POST /{{tenant}}/oauth2/v2.0/token HTTP/1.1 //Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id={{client_id}}
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret={{client_secret}}
&grant_type=client_credentials
以下示例显示了成功响应:
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJu… "
}
Note: 你正在此处使用 客户端凭据流。 请确保获取应用访问令牌,而不是用户访问令牌。
步骤 6:创建新连接
连接是外部数据的逻辑容器,您可以作为一个单元进行管理。 选择连接名称、说明和 ID。 从管理员获取连接到数据源的必要详细信息,并提供一种机制,在设置连接时授权处理内容源。 可使用 Microsoft Graph SDK 和API对连接器设置进行编程。 如果要存储凭据,则可以使用Azure Key Vault。
POST /external/connections
下面展示了示例请求。
POST https://graph.microsoft.com/beta/external/connections
Content-type: application/json
{
"id": "contosotasks",
"name": "Contoso Tasks",
"description": "Connection to index Contoso task management system"
}
下面介绍响应示例。
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#connections/$entity",
"id": "contosotasks",
"name": "Contoso Tasks",
"description": "Connection to index Contoso task management system",
"state": null,
"configuration": {
"authorizedApps": [
"a47b35b7-6271-4e6d-9e27-2450a8b9c6b6"
]
}
}
以下是 “创建连接” 部分的屏幕快照。
"创建连接"分区的屏幕截图
步骤 7:注册连接架构
连接架构确定如何在各种 Microsoft Graph 体验中使用你的内容。 架构是计划与其特性、标签和别名一起添加到连接中的所有属性的简单列表。 向连接添加项目前,必须注册架构。
POST /external/connections/{id}/schema
下面展示了示例请求。
POST https://graph.microsoft.com/beta/external/connections/contosotasks/schema
Content-type: application/json
Prefer: respond-async
{
"baseType": "microsoft.graph.externalItem",
"properties": [
{
"name": "title",
"type": "String",
"isSearchable": "true",
"isQueryable": "true",
"isRetrievable": "true",
"labels": [
"title"
]
},
{
"aliases": "creator",
"name": "createdBy",
"type": "String",
"isSearchable": "true",
"isQueryable": "true",
"isRetrievable": "false",
"isRefinable": "false",
"labels": [
"createdBy"
]
},
{
"aliases": "editedDate",
"name": "lastEditedDate",
"type": "DateTime",
"isSearchable": "false",
"isQueryable": "true",
"isRetrievable": "true",
"isRefinable": "true",
"labels": [
"lastModifiedDateTime"
]
}
]
}
下面介绍响应示例。
HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/beta/external/connections/contosotasks/operations/616bfeed-666f-4ce0-8cd9-058939010bfc
Note: 注册连接架构是一个异步操作,因此在连接架构进入“完成”状态之前,请勿将项目进入连接中。要检查连接架构状态,请执行以下请求:
GET /external/connections/contosotasks/operations/616bfeed-666f-4ce0-8cd9-058939010bfc
下面是另一个请求示例。
Request
GET https://graph.microsoft.com/beta/external/connections/operations/616bfeed-666f-4ce0-8cd9-058939010bfc
下面是另一个响应示例。
HTTP/1.1 200 OK
Content-type: application/json
{
@odata.context":"https://graph.microsoft.com/beta/$metadata#external/connections('coursecatalog')/operations/$entity",
"id": "aa9186d2-893c-4361-ca51-431d88fa45d8",
"name": "Contoso Tasks",
"status": "inprogress",
"error": null
}
下面是"获取连接操作状态"部分屏幕截图。
显示正在进行状态的"获取操作状态"分区的屏幕截图
将连接架构操作状态从 “进行中” 更改为 “完成”后, 您可以提取该连接的项目。
在连接状态从 草稿 变为 就绪 后,可以将项目加入当前连接。
步骤 8:添加外部组成员(可选)
如果外部服务使用非 Azure AD 访问控制列表 (ACL),请同步这些权限。
外部组(以及 Azure Active Directory 用户和组)用于设置已添加到 Microsoft Graph 连接的 externalItems 的权限。有关详细信息,请参阅 externalGroup。
这是一个请求示例。
POST https://graph.microsoft.com/beta/external/connections/contosotasks/groups/31bea3d537902000/members
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.externalGroupMember",
"id": "1431b9c38ee647f6a",
"type": "group",
"identitySource": "external"
}
这是一个响应示例。
HTTP/1.1 201 Created
Content-Type: application/json
{
"@odata.type": "#microsoft.graph.externalGroupMember",
"id": "14m1b9c38qe647f6a",
"type": "group",
"identitySource": "external"
}
步骤 9:引入项目
创建连接后,可以添加内容。 数据源中的每个项目都必须用唯一的项目 id 表示为 Microsoft Graph 中的 externalItem。 此 ID 用于在 Microsoft Graph 中创建、更新或删除项目。 可使用数据源中的主键作为源 itemId 或来自一个或多个字段的主键。 控件 externalItem 三个关键组件:访问控制列表、属性和内容。
如果有二进制文件,则必须进行分析以获得元数据和内容的文本版本。 如果有 PDF 或 BMP 文件等非文本内容,则必须使用对象字符识别将内容转换为文本。
你负责将源权限转换为 grant 或 deny。 Deny 优先级高于 grant。
请求示例如下所示。
PUT https://graph.microsoft.com/beta/external/connections/contosohr/items/TSP228082938
Content-type: application/json
{
"@odata.type": "microsoft.graph.externalItem",
"acl": [
{
"type": "user",
"value": "e811976d-83df-4cbd-8b9b-5215b18aa874",
"accessType": "grant",
"identitySource": "azureActiveDirectory"
},
{
"type": "group",
"value": "14m1b9c38qe647f6a",
"accessType": "deny",
"identitySource": "external"
}
],
"properties": {
"ticketID": "1158",
"priority": 1,
"title": "Filter design",
},
"content": {
"value": "Build filtering capability by...",
"type": "text"
}
}
下面是成功响应的示例。
HTTP/1.1 200 OK
错误处理
要详细了解如何解决错误,请参阅 解决 Microsoft Graph 授权错误。
另请参阅
历史资料。此文对应 2023-02-03 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 mecampos)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
