设置 Openflow Connector for SharePoint

备注

使用该连接器需遵守 连接器条款

本主题介绍 Openflow Connector for SharePoint 的设置步骤。

先决条件

  1. 确保您已查看 Openflow Connector for SharePoint

  2. 确保您已 设置 Openflow

获取凭据

作为 SharePoint 管理员,请执行以下操作:

  1. 确保您有具有以下 Microsoft Graph 权限的 Microsoft Graph (https://learn.microsoft.com/en-us/graph/overview) 应用程序:

    1. Sites.Selected (https://learn.microsoft.com/en-us/graph/permissions-reference#sitesselected):仅限访问指定的站点。

    2. Files.SelectedOperations.Selected (https://learn.microsoft.com/en-us/graph/permissions-reference#filesselectedoperationsselected):仅限访问指定站点中的文件。

    3. GroupMember.Read.All (https://learn.microsoft.com/en-us/graph/permissions-reference#groupmemberreadall):用于解析 SharePoint 组权限。

    4. User.ReadBasic.All (https://learn.microsoft.com/en-us/graph/permissions-reference#userreadbasicall):用于解析 Microsoft365 用户电子邮件。

  2. 按照“在没有用户的情况下获取访问权限”中的说明,配置 SharePoint 以启用 OAuth 身份验证。连接器使用以下 Microsoft Graph APIs 从 SharePoint 获取数据:

    1. 下载 driveItem 内容 (https://learn.microsoft.com/en-us/graph/api/driveitem-get-content?view=graph-rest-1.0&tabs=http)

    2. 获取 driveItem 元数据 (https://learn.microsoft.com/en-us/graph/api/driveitem-get?view=graph-rest-1.0&tabs=http)

    3. driveItem: delta

    4. 列出 driveItem 权限 (https://learn.microsoft.com/en-us/graph/api/driveitem-list-permissions?view=graph-rest-1.0&tabs=http)

    5. group: delta

    6. 列出组成员 (https://learn.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0&tabs=http)

    7. 获取用户 (https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=http)

  3. 从您的 Azure 或 Office 365 账户管理员处获取您的 Microsoft 365 SharePoint 站点的站点 URL(其中包含您要引入到 Snowflake 中的文件或文件夹)和凭据。

设置 Snowflake 账户

作为 Snowflake 账户管理员,手动或使用下面附带的脚本执行以下任务:

  1. 创建新角色或使用现有角色并授予 数据库权限

  2. 创建类型为 SERVICE 的新 Snowflake 服务用户。

  3. 向该 Snowflake 服务用户授予您在前面步骤中创建的角色。

  4. 为第 2 步中创建的 Snowflake SERVICE 用户配置 密钥对身份验证

  5. Snowflake 强烈建议执行此步骤。配置 Openflow 支持的密钥管理器(例如 AWS、Azure 和 Hashicorp),并将公钥和私钥存储在密钥存储库中。

    备注

    如果您出于任何原因不希望使用密钥管理器,则您有责任根据组织的安全策略保护用于密钥对身份验证的公钥和私钥文件。

    1. 配置密钥管理器后,确定如何对其进行身份验证。在 AWS 中,建议您使用与 Openflow 关联的 EC2 实例角色,因为这样就无需保留其他密钥。

    2. 在 Openflow 中,从右上角的汉堡菜单中配置与此密钥管理器关联的参数提供商。导航到 Controller Settings » Parameter Provider,然后提取您的参数值。

    3. 此时,可以使用关联的参数路径引用所有凭据,无需在 Openflow 中保留敏感值。

  6. 如果任何其他 Snowflake 用户需要访问连接器引入的原始文档和表(例如,在 Snowflake 中进行自定义处理),则授予这些用户在步骤 1 中创建的角色。

  7. 指定一个仓库供连接器使用。从最小的仓库规模开始,然后根据要复制的表数量和传输的数据量来测试规模。相较于扩大仓库规模,采用 多集群仓库 通常能更有效地应对海量表数量的扩展需求。

示例设置

--The following script assumes you'll need to create all required roles, users, and objects.
--However, you may want to reuse some that are already in existence.

--Create a Snowflake service user to manage the connector
USE ROLE USERADMIN;
CREATE USER <openflow_service_user> TYPE=SERVICE COMMENT='Service user for Openflow automation';

--Create a pair of secure keys (public and private). For more information, see
--key-pair authentication. Store the private key for the user in a file to supply
--to the connector’s configuration. Assign the public key to the Snowflake service user:
ALTER USER <openflow_service_user> SET RSA_PUBLIC_KEY = '<pubkey>';


--Create a role to manage the connector and the associated data and
--grant it to that user
USE ROLE SECURITYADMIN;
CREATE ROLE <openflow_connector_admin_role>;
GRANT ROLE <openflow_connector_admin_role> TO USER <openflow_service_user>;


--The following block is for USE CASE 2 (Cortex connect) ONLY
--Create a role for read access to the cortex search service created by this connector.
--This role should be granted to any role that will use the service
CREATE ROLE <cortex_search_service_read_only_role>;
GRANT ROLE <cortex_search_service_read_only_role> TO ROLE <whatever_roles_will_access_search_service>;

--Create the database the data will be stored in and grant usage to the roles created
USE ROLE ACCOUNTADMIN; --use whatever role you want to own your DB
CREATE DATABASE IF NOT EXISTS <destination_database>;
GRANT USAGE ON DATABASE <destination_database> TO ROLE <openflow_connector_admin_role>;

--Create the schema the data will be stored in and grant the necessary privileges
--on that schema to the connector admin role:
USE DATABASE <destination_database>;
CREATE SCHEMA IF NOT EXISTS <destination_schema>;
GRANT USAGE ON SCHEMA <destination_schema> TO ROLE <openflow_connector_admin_role>;
GRANT CREATE TABLE, CREATE DYNAMIC TABLE, CREATE STAGE, CREATE SEQUENCE, CREATE CORTEX
SEARCH SERVICE ON SCHEMA <destination_schema> TO ROLE <openflow_connector_admin_role>;

--The following block is for CASE 2 (Cortex connect) ONLY
--Grant the Cortex read-only role access to the database and schema
GRANT USAGE ON DATABASE <destination_database> TO ROLE <cortex_search_service_read_only_role>;
GRANT USAGE ON SCHEMA <destination_schema> TO ROLE <cortex_search_service_read_only_role>;

--Create the warehouse this connector will use if it doesn't already exist. Grant the
--appropriate privileges to the connector admin role. Adjust the size according to your needs.
CREATE WAREHOUSE <openflow_warehouse>
WITH
   WAREHOUSE_SIZE = 'MEDIUM'
   AUTO_SUSPEND = 300
   AUTO_RESUME = TRUE;
GRANT USAGE, OPERATE ON WAREHOUSE <openflow_warehouse> TO ROLE <openflow_connector_admin_role>;
Copy

用例 1:仅使用连接器引入文件

使用连接器以执行以下操作:

  • 对引入的文件执行自定义处理

  • 引入 Sharepoint 文件和权限并使其保持最新状态

设置连接器

作为数据工程师,执行以下任务以配置连接器:

安装连接器

  1. 导航到 Openflow“Overview”页面。在 Featured connectors 部分中,选择 View more connectors

  2. 在 Openflow 连接器页面上,找到连接器并选择 Add to runtime

  3. Select runtime 对话框中,从 Available runtimes 下拉列表中选择您的运行时。

  4. 选择 Add

    备注

    在安装连接器之前,请确保在 Snowflake 中为连接器创建了数据库和架构,用于存储引入的数据。

  5. 使用您的 Snowflake 账户凭据对部署进行身份验证,并在系统提示时选择 Allow,以允许运行时应用程序访问您的 Snowflake 账户。连接器安装过程需要几分钟才能完成。

  6. 使用您的 Snowflake 账户凭据进行运行时身份验证。

此时将显示 Openflow 画布,其中添加了连接器进程组。

配置连接器

  1. 填充进程组参数

    1. 右键点击导入的进程组并选择 Parameters

    2. 根据 Sharepoint 引入参数Sharepoint 目标参数`Sharepoint 源参数`_中的描述,输入所需的参数值。

Sharepoint 源参数

参数

描述

SharePoint 站点 URL

连接器将从中引入内容的 URL 或 SharePoint 站点

SharePoint 客户端 ID

Microsoft Entra 客户端 ID。要了解客户端 ID 以及如何在 Microsoft Entra 中找到它,请参阅 `应用程序 ID(客户端 ID)<https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#application-id-client-id>`_

SharePoint 客户端密钥

Microsoft Entra 客户端密钥。要了解客户端密钥以及如何在 Microsoft Entra 中找到它,请参阅 证书与密钥 (https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#certificates--secrets)。

SharePoint 租户 ID

Microsoft Entra 租户 ID。要了解租户 ID 以及如何在 Microsoft Entra 中找到它,请参阅 查找您的 Microsoft 365 租户ID (https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id)。

Sharepoint 应用程序私钥

生成的 PEM 格式的应用程序私钥。密钥必须未加密。

Sharepoint 站点域名

同步的 Sharepoint 站点的域名。

Sharepoint 应用程序证书

生成的 PEM 格式的应用程序证书。

Sharepoint 目标参数

参数

描述

目标数据库

用于永久保存数据的数据库。它必须已经存在于 Snowflake 中

目标架构

用于永久保存数据的架构。它必须已经存在于 Snowflake 中

Snowflake 账户标识符

Snowflake 账户名称格式为 [organization-name]-[account-name],数据永久保存在其中

Snowflake 身份验证策略

对 Snowflake 进行身份验证的策略。可能的值:SNOWFLAKE_SESSION_TOKEN – 当我们在 SPCS 上运行流时;KEY_PAIR – 当我们想使用私钥设置访问权限时

Snowflake 私钥

用于身份验证的 RSA 私钥。RSA 密钥必须按照 PKCS8 标准进行格式化,并具有标准的 PEM 头尾标记。请注意,必须定义 Snowflake 私钥文件或 Snowflake 私钥

Snowflake 私钥文件

该文件包含用于对 Snowflake 进行身份验证的 RSA 私钥,该私钥根据 PKCS8 标准进行格式化,并具有标准的 PEM 头尾标记。头标记行以 -----BEGIN PRIVATE 开头。选中 Reference asset 复选框,上传私钥文件。

Snowflake 私钥密码

与 Snowflake 私钥文件关联的密码

Snowflake 角色

查询执行期间使用的 Snowflake 角色

Snowflake 用户名

用于连接到 Snowflake 实例的用户名

Snowflake 仓库

用于运行查询的 Snowflake 仓库

Sharepoint 引入参数

参数

描述

Sharepoint 站点组已启用

指定是否启用站点组功能。

SharePoint 源文件夹

此文件夹及其所有子文件夹中支持的文件将引入 Snowflake 中。此文件夹路径是 Shared Documents 库的相对路径。

要引入的文件扩展名

以逗号分隔的列表,用于指定要引入的文件扩展名。如果可能,连接器会尝试先将文件转换为 PDF 格式。尽管如此,系统仍会基于原始文件扩展名执行扩展名检查。要了解可转换的格式,请参阅 格式选项 (https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format?view=graph-rest-1.0&tabs=http#format-options)。如果 Cortex Parse Document 不支持某些指定的文件扩展名,则连接器将忽略这些文件、在事件日志中记录警告消息,并继续处理其他文件。

Sharepoint Document 库名称

SharePoint 站点中的一个库,用于从中引入文件。

Snowflake 文件哈希表名

用于存储文件哈希值以确定内容是否已更改的表的名称。通常不应更改此参数。

  1. 运行流。

    1. 启动进程组。该流将在 Snowflake 中创建所有必需的对象。

    2. 右键点击导入的进程组并选择 Start

用例 2:使用连接器定义引入文件,并使用 Cortex 执行处理

使用预定义的流定义以执行以下操作:

  • 为组织 SharePoint 站点内的公共文档创建 AI 助手。

  • 使您的 AI 助手遵守组织 SharePoint 站点中指定的访问控制。

设置连接器

作为数据工程师,执行以下任务以配置连接器:

安装连接器

  1. 在 Snowflake 中为连接器创建数据库和架构,以存储引入的数据。向第一步中创建的角色授予所需的 数据库权限。用实际值替换角色占位符,然后使用以下 SQL 命令:

    CREATE DATABASE DESTINATION_DB;
    CREATE SCHEMA DESTINATION_DB.DESTINATION_SCHEMA;
    GRANT USAGE ON DATABASE DESTINATION_DB TO ROLE <CONNECTOR_ROLE>;
    GRANT USAGE ON SCHEMA DESTINATION_DB.DESTINATION_SCHEMA TO ROLE <CONNECTOR_ROLE>;
    GRANT CREATE TABLE ON SCHEMA DESTINATION_DB.DESTINATION_SCHEMA TO ROLE <CONNECTOR_ROLE>;
    
    Copy
  1. 导航到 Openflow“Overview”页面。在 Featured connectors 部分中,选择 View more connectors

  2. 在 Openflow 连接器页面上,找到连接器并选择 Add to runtime

  3. Select runtime 对话框中,从 Available runtimes 下拉列表中选择您的运行时。

  4. 选择 Add

    备注

    在安装连接器之前,请确保在 Snowflake 中为连接器创建了数据库和架构,用于存储引入的数据。

  5. 使用您的 Snowflake 账户凭据对部署进行身份验证,并在系统提示时选择 Allow,以允许运行时应用程序访问您的 Snowflake 账户。连接器安装过程需要几分钟才能完成。

  6. 使用您的 Snowflake 账户凭据进行运行时身份验证。

此时将显示 Openflow 画布,其中添加了连接器进程组。

配置连接器

  1. 填充进程组参数

    1. 右键点击导入的进程组并选择 Parameters

    2. 根据 Sharepoint 源参数Sharepoint 目标参数Sharepoint 引入参数 中的描述,输入所需的参数值。

Sharepoint Cortex Connect 源参数

参数

描述

SharePoint 站点 URL

连接器将从中引入内容的 URL 或 SharePoint 站点

SharePoint 客户端 ID

Microsoft Entra 客户端 ID。要了解客户端 ID 以及如何在 Microsoft Entra 中找到它,请参阅 `应用程序 ID(客户端 ID)<https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#application-id-client-id>`_

SharePoint 客户端密钥

Microsoft Entra 客户端密钥。要了解客户端密钥以及如何在 Microsoft Entra 中找到它,请参阅 证书与密钥 (https://learn.microsoft.com/en-us/azure/healthcare-apis/register-application#certificates--secrets)。

SharePoint 租户 ID

Microsoft Entra 租户 ID。要了解租户 ID 以及如何在 Microsoft Entra 中找到它,请参阅 查找您的 Microsoft 365 租户ID (https://learn.microsoft.com/en-us/sharepoint/find-your-office-365-tenant-id)。

Sharepoint 应用程序私钥

生成的 PEM 格式的应用程序私钥。密钥必须未加密。

Sharepoint 站点域名

同步的 Sharepoint 站点的域名。

Sharepoint 应用程序证书

生成的 PEM 格式的应用程序证书。

Sharepoint Cortex Connect 目标参数

参数

描述

目标数据库

用于永久保存数据的数据库。它必须已经存在于 Snowflake 中

目标架构

用于永久保存数据的架构。它必须已经存在于 Snowflake 中

Snowflake 账户标识符

Snowflake 账户名称格式为 [organization-name]-[account-name],数据永久保存在其中

Snowflake 身份验证策略

对 Snowflake 进行身份验证的策略。可能的值:SNOWFLAKE_SESSION_TOKEN – 当我们在 SPCS 上运行流时;KEY_PAIR – 当我们想使用私钥设置访问权限时

Snowflake 私钥

用于身份验证的 RSA 私钥。RSA 密钥必须按照 PKCS8 标准进行格式化,并具有标准的 PEM 头尾标记。请注意,必须定义 Snowflake 私钥文件或 Snowflake 私钥

Snowflake 私钥文件

该文件包含用于对 Snowflake 进行身份验证的 RSA 私钥,该私钥根据 PKCS8 标准进行格式化,并具有标准的 PEM 头尾标记。头标记行以 -----BEGIN PRIVATE 开头。选中 Reference asset 复选框,上传私钥文件。

Snowflake 私钥密码

与 Snowflake 私钥文件关联的密码

Snowflake 角色

查询执行期间使用的 Snowflake 角色

Snowflake 用户名

用于连接到 Snowflake 实例的用户名

Snowflake 仓库

用于运行查询的 Snowflake 仓库

Sharepoint Cortex Connect 引入参数

参数

描述

Sharepoint 站点组已启用

指定是否启用站点组功能。

SharePoint 源文件夹

此文件夹及其所有子文件夹中支持的文件将引入 Snowflake 中。此文件夹路径是 Shared Documents 库的相对路径。

要引入的文件扩展名

以逗号分隔的列表,用于指定要引入的文件扩展名。如果可能,连接器会尝试先将文件转换为 PDF 格式。尽管如此,系统仍会基于原始文件扩展名执行扩展名检查。要了解可转换的格式,请参阅 格式选项 (https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format?view=graph-rest-1.0&tabs=http#format-options)。如果 Cortex Parse Document 不支持某些指定的文件扩展名,则连接器将忽略这些文件、在事件日志中记录警告消息,并继续处理其他文件。

Sharepoint Document 库名称

SharePoint 站点中的一个库,用于从中引入文件。

Snowflake 文件哈希表名

用于存储文件哈希值以确定内容是否已更改的表的名称。通常不应更改此参数。

OCR 模式

使用 Cortex PARSE_DOCUMENT 函数解析文件时使用的 OCR 模式。该值可以是 OCRLAYOUT。在 OCR 模式下,仅提取原始文本内容,忽略格式和表结构。在 LAYOUT 模式下,输出将表结构保留为 Markdown。

Snowflake Cortex Search 服务用户角色

获分配 Cortex Search 服务使用权限的角色的标识符。

  1. 右键点击平面并选择 Enable all Controller Services

  2. 右键点击导入的进程组并选择 Start。连接器开始数据引入。

  3. 查询 Cortex Search 服务

用例 3:自定义连接器定义

自定义连接器定义以执行以下操作:

  • 使用 Document AI 处理引入的文件。

  • 对引入的文件执行自定义处理。

设置连接器

作为数据工程师,执行以下任务以配置连接器:

安装连接器

  1. 导航到 Openflow“Overview”页面。在 Featured connectors 部分中,选择 View more connectors

  2. 在 Openflow 连接器页面上,找到连接器并选择 Add to runtime

  3. Select runtime 对话框中,从 Available runtimes 下拉列表中选择您的运行时。

  4. 选择 Add

    备注

    在安装连接器之前,请确保在 Snowflake 中为连接器创建了数据库和架构,用于存储引入的数据。

  5. 使用您的 Snowflake 账户凭据对部署进行身份验证,并在系统提示时选择 Allow,以允许运行时应用程序访问您的 Snowflake 账户。连接器安装过程需要几分钟才能完成。

  6. 使用您的 Snowflake 账户凭据进行运行时身份验证。

此时将显示 Openflow 画布,其中添加了连接器进程组。

配置连接器

  1. 自定义连接器定义。

    1. 移除以下进程组:

      • 检查内容是否重复

      • Snowflake 暂存区和解析 PDF

      • 更新 Snowflake Cortex

      • (可选)处理 Microsoft365 组

    2. 将任何自定义处理附加到 Process SharePoint Metadata 进程组的输出。每个流文件代表一项 SharePoint 文件更改。

  2. 填充进程组参数。遵循与用例 1 相同的进程。请注意,修改连接器定义后,可能并不需要所有参数。

  3. 运行流。

    1. 启动进程组。该流将在 Snowflake 中创建所有必需的对象。

    2. 右键点击导入的进程组并选择 Start

  4. 查询 Cortex Search 服务

启用 Sharepoint 站点组

适用于站点组的 Microsoft Graph 应用程序

除了在 获取凭据 中指定的步骤外,另请执行以下操作:

  1. 添加 Sites.Selected (https://learn.microsoft.com/en-us/graph/permissions-reference#sitesselected) SharePoint 权限。

    备注

    您应该会在 Microsoft Graph 和 SharePoint 权限中看到 Sites.Selected

  2. 生成密钥对 (https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate)。或者,您可以运行以下命令,使用 openssl 创建自签名证书:

    openssl req -x509 -nodes -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365
    
    Copy

    备注

    上面的命令不对生成的私钥加密。如果您要生成加密密钥,请移除 -nodes 实参。

  3. 将证书附加 (https://learn.microsoft.com/en-us/graph/applications-how-to-add-certificate?tabs=http) 到 Microsoft Graph 应用程序。

查询 Cortex Search 服务

您可以使用 Cortex Search 服务构建聊天和搜索应用程序,以便与 SharePoint 中的文档聊天或查询文档。

安装和配置连接器并开始从 Sharepoint 引入内容后,您就可以查询 Cortex Search 服务。有关使用 Cortex Search 的更多信息,请参阅 查询 Cortex Search 服务

筛选器响应

要将 Cortex Search 服务的响应限制为 SharePoint 中特定用户可以访问的文档,可以在查询 Cortex Search 时指定一个包含用户 ID 或电子邮件地址的筛选器。例如,filter.@contains.user_idsfilter.@contains.user_emails。连接器创建的 Cortex Search 服务名称是 search_service 并位于 Cortex 架构中。

在 SQL 工作表中运行以下 SQL 代码,利用从 SharePoint 站点引入的文件查询 Cortex Search 服务。

替换以下内容:

  • application_instance_name:数据库和连接器应用程序实例的名称。

  • user_emailID:要筛选响应的用户的电子邮件 ID。

  • your_question:要获取响应的问题。

  • number_of_results:要在响应中返回的最大结果数。最大值为 1000,默认值为 10。

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    '<application_instance_name>.cortex.search_service',
      '{
        "query": "<your_question>",
         "columns": ["chunk", "web_url"],
         "filter": {"@contains": {"user_emails": "<user_emailID>"} },
         "limit": <number_of_results>
       }'
   )
)['results'] AS results
Copy

以下是您可以为 columns 输入的值的完整列表:

列名称

类型

描述

full_name

字符串

Sharepoint 站点文档根目录中文件的完整路径。示例:folder_1/folder_2/file_name.pdf

web_url

字符串

在浏览器中显示 Sharepoint 原始文件的 URL。

last_modified_date_time

字符串

项目最近一次修改的日期和时间。

chunk

字符串

与 Cortex Search 查询匹配的文档中的一段文本。

user_ids

数组

可访问文档的 Microsoft 365 用户 IDs ID 的数组。它还包括分配给文档的所有 Microsoft 365 组的用户 IDs。要查找特定用户 ID,请参阅 获取用户 (https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0&tabs=http)。

user_emails

数组

可访问文档的 Microsoft 365 用户电子邮件 IDs 的数组。它还包括分配给文档的所有 Microsoft 365 组的用户电子邮件 IDs。

示例:向 AI 助手查询人力资源 (HR) 信息

您可以使用 Cortex Search 查询 AI 助手,为员工聊天提供最新版本的 HR 信息,如入职、行为规范、团队流程和组织政策等。使用响应筛选器,您还可以允许 HR 团队成员查询员工合同,同时遵守 SharePoint 中配置的访问控制。

SQL 工作表 中运行以下内容,利用从 SharePoint 引入的文件查询 Cortex Search 服务。选择数据库为应用程序实例名称,架构为 Cortex

替换以下内容:

  • application_instance_name:数据库和连接器应用程序实例的名称。

  • user_emailID:要筛选响应的用户的电子邮件 ID。

SELECT PARSE_JSON(
     SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
          '<application_instance_name>.cortex.search_service',
          '{
             "query": "What is my vacation carry over policy?",
             "columns": ["chunk", "web_url"],
             "filter": {"@contains": {"user_emails": "<user_emailID>"} },
             "limit": 1
          }'
     )
 )['results'] AS results
Copy
语言: 中文