大网数据广告活动
Microsoft Graph 接口

将 Postman 与 Microsoft Graph 连接器 API 一并使用

· 52CE 我爱测

按照本指南中的步骤使用 Postman API 平台创建Microsoft Graph连接器 API。

Postman 是用于构建和使用 API 的 API 平台。 Postman 简化了 API 生命周期的每个步骤并简化了协作,以便可以更快地创建更好的 API。

本文介绍如何将 Microsoft Graph 连接器 API 与 Postman 配合使用。

先决条件

  • Microsoft 帐户或者工作或学校帐户。
  • 访问 Microsoft 365 开发人员租户。如果没有,可以注册 Microsoft 365 开发人员计划,以获取免费的开发人员订阅。

步骤 1:分叉 Microsoft Graph Postman 集合

要使用 Postman 集合,需要将其导入到 Postman 工作区。在 Web 浏览器执行此操作。

  1. 转到 Postman 并登录。 如果已有 Postman 帐户, 登录。

  2. 登录后,转到以下 URL:https://www.postman.com/microsoftgraph/workspace/microsoft-graph/collection/455214-085f7047-1bec-4570-9ed0-3a7253be148,然后选择 Microsoft Graph 集合。

  3. 选择右侧的三个点,然后选择“创建分叉”。

    显示 Postman 中 Microsoft Graph 集合和创建分支选项的屏幕截图

  4. 在打开的对话框中,输入标签以标识您的分支。 在“工作区”下拉菜单中,选择“我的工作区”,然后选择“分支集合”。

    显示 Postman 中的"分支集合"对话框和用于输入标签选项的屏幕截图,并选择"我的工作区"

  5. 转到“工作区” > “我的工作区”,以查看创建的分支。 可在“应用程序”下找到 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) 应用程序,并根据想要调用的请求向其授予合适权限。

  1. 转到 portal.azure.com 并使用开发者租户管理员帐户登录。
  2. 在 Azure 服务 下,选择“Azure Active Directory”。
  3. 在左侧菜单上,选择 注册。
  4. 在水平菜单中,单击“新建注册”。
  5. 将“应用名称”设置为“Parts Inventory”。
  6. 将“重定向 URI”设置为“https://oauth.pstmn.io/v1/browser-callback”。
  7. 选择“注册”。
  8. 在左侧菜单上,选择 API 权限。
  9. 在水平菜单上,选择“添加权限” > “Microsoft Graph” > “委派权限”。
  10. 开始键入 ExternalItem.ReadWrite.All,然后选择 ExternalItem.ReadWrite.All。
  11. 选择“应用程序权限”,键入 ExternalItem,然后选择“应用程序权限”。
  12. 展开 ExternalItem 选项,然后选择 ExternalItem.ReadWrite.All。
  13. 选择 添加权限。
  14. 在水平菜单上,选择“授予管理员同意”,然后选择“是”。
  15. 在左侧的菜单中,选择“概述”。 在这里,可以获取 应用程序(客户端)ID 和 目录(租户)ID。 步骤 4 中将需要使用这些信息。
  16. 在左侧菜单中,选择“证书和机密”。
  17. 选择“新建客户端机密”,输入说明,然后选择“添加”。 复制新的客户端密码值;步骤 4 中将需要使用该密码。

应用程序现在配置了两个权限。 ExternalItem.ReadWrite.All 添加为委派权限,这是需要登录用户的权限。 应用程序可以代表用户读取/写入外部项。 ExternalItem.ReadWrite.All 添加为应用程序权限,这是不需要登录用户的权限。 应用程序可以代表自己读取/写入外部项。

步骤 4:配置身份验证

在此步骤中,请在 Postman 中设置用于检索访问令牌的环境变量。

  1. 选择 "Microsoft Graph" 选项卡,然后转到 "变量" 部分。

    Microsoft Graph 连接器 API 选项卡和"变量"部分屏幕截图

  2. 在“变量”部分,使用步骤 3 中的信息提供所需信息:

    • 将 租户 的当前值设置为步骤 3.15 中的目录(租户)ID 值。
    • 将 客户端_id 的当前值设置为步骤 3.15 中的应用程序(客户端)ID 值。
    • 将 客户端_密码 的当前值设置为步骤 3.17 中的客户端密码值。
    • 将 用户名 的当前值设置为 admin@xxxxxxx.onmicrosoft.com。
    • 将 密码 的当前值设置为租户管理员密码。

    显示所选变量的屏幕截图

  3. 选择“保存” / “更新”。

步骤 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,规范化链接,移除外部媒体和导航标记。

资料来源与适用范围

资料来源
Microsoft / Microsoft Graph 中文文档历史快照
适用范围
历史中文快照 2023-02-03;详见原文产品版本;文档日期 未标明
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。