ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

Pathway 实战:使用官方示例程序验证 SharePoint 连接器连通性

Pathway 实战:使用官方示例程序验证 SharePoint 连接器连通性 Pathway 实战使用官方示例程序验证 SharePoint 连接器连通性【免费下载链接】pathwayPython ETL framework for stream processing, real-time analytics, LLM pipelines, and RAG.项目地址: https://gitcode.com/GitHub_Trending/pa/pathway本篇文章围绕 Pathway 仓库中 sharepoint-test 示例程序 与其 README 说明 展开系统讲解如何配置并运行 Pathway 的 SharePoint 连接器以打通微软 SharePoint 站点的数据读取链路。读完本文你将掌握该示例的完整运行步骤、sharepoint.read全部核心参数的含义与取值并借助仓库源码与集成测试理解底层认证、快照扫描与数据输出的工作原理从而快速判断你的 SharePoint 环境应用注册、证书、目录权限是否配置正确。示例程序定位一个专为连通性测试设计的最小案例在部署任何真实的读取 SharePoint → 进入 Pathway 实时管道业务之前先用最小程序验证连接是成本最低的排障手段。仓库中的 examples/projects/sharepoint-test 目录正是为此而生它仅包含两个文件README.md用法说明sharepoint_test.py可运行的测试脚本。从仓库结构看该示例还同时在开发者文档的模板库中维护了一份镜像说明见 docs/2.developers/7.templates/ETL/_readmes/sharepoint-test.md其内容与示例 README 完全一致方便在模板目录中浏览。示例脚本的完整源码如下sharepoint_test.pyimport pathway as pw from pathway.xpacks.connectors import sharepoint if __name__ __main__: table sharepoint.read( url..., # Example: https://company.sharepoint.com/sites/MySite root_path..., # Example: Shared Documents/Indexer tenant..., # Normally uuid4 client_id..., # Normally uuid4 thumbprint..., # Certificates thumbprint cert_path..., # A path to the .pem-file for the certificate modestatic, ) pw.io.jsonlines.write(table, contents.txt) pw.run(monitoring_levelpw.MonitoringLevel.NONE)它的逻辑非常简洁用sharepoint.read读取指定 SharePoint 站点目录中的文件通过 jsonlines 输出 写入本地contents.txt最后调用pw.run启动引擎执行整张数据流图。这正是典型的最小可验证程序结构——如果连接配置有误程序会直接报错如果配置正确运行结束后contents.txt中会出现数据行。前置条件证书认证、应用授权与许可证由于该连接器采用微软 Azure ADEntra ID的应用 客户端证书方式进行认证示例 README 提到的占位参数背后对应着一整套 SharePoint 应用注册与授权工作参数含义典型形态urlSharePoint 站点 URL含站点路径https://company.sharepoint.com/sites/MySitetenant租户 ID即 Azure AD 中的目录 ID形如 UUIDGuid的字符串client_id已授权访问 SharePoint 的应用ApplicationClient ID形如 UUIDGuid的字符串thumbprint客户端证书的指纹thumbprint证书十六进制指纹cert_path证书文件路径通常为.pem格式如./certificate.pem从连接器源码 python/pathway/xpacks/connectors/sharepoint/init.py 可以确认认证链路的具体实现_ContextWrapper内部使用 office365 Python 库的ClientContext(url).with_client_certificate(tenant..., client_id..., thumbprint..., cert_path...)构造 SharePoint 客户端上下文随后加载context.web并执行一次查询来验证凭据是否可用。也就是说示例中填写的五个认证参数会被原样传递给微软的证书认证接口任何一项错误都会导致认证失败。此外还有两点需要注意许可证要求该连接器属于 Pathway 的扩展包xpack能力。连接器入口read的文档字符串明确注明Requires a valid Pathway Live Data Framework Scale license key同时_SharePointSubject在初始化时会调用_check_entitlements(xpack-sharepoint)进行授权校验源码。示例 README 中给出的运行方式是把它作为环境变量注入PATHWAY_LICENSE_KEY... python sharepoint_test.py如果本地未配置许可证可通过该环境变量在运行时提供。测试目录必须非空README 在末尾特别提示 Ensure that your SharePoint space contains at least one file for this test to work.。这是因为整个测试的判断标准是contents.txt中是否出现内容——若目标目录为空即使连接成功也不会有任何数据行写入从而无法与失败场景区分。建议在root_path指向的目录中预先放置一个已知文件用于验证。逐参数深入sharepoint.read完整参数语义示例只使用了 6 个必要参数并把mode固定为static但连接器实际支持更丰富的配置。以源码中的完整函数签名为准python/pathway/xpacks/connectors/sharepoint/init.pydef read( url: str, *, tenant: str, client_id: str, cert_path: str, thumbprint: str, root_path: str, mode: str streaming, format: Literal[binary, only_metadata] binary, recursive: bool True, object_size_limit: int | None None, with_metadata: bool False, refresh_interval: DurationLike 30, max_failed_attempts_in_row: int | None 8, max_backlog_size: int | None None, ) - Table各参数要点如下url与root_path定位读取范围url指向 SharePoint 站点本身例如https://company.sharepoint.com/sites/Datasets。仓库开发者文档同时指出从站点子站subsite读取数据同样受支持——将子站 URL 填入url即可如https://company.sharepoint.com/sites/Datasets/vendor。root_path指向站点内要读取的目录或单个文件采用服务器相对路径如Shared Documents/Data。mode读取模式示例中固定为static默认值为streaming连接器每隔refresh_interval秒扫描一次目录增量地反映新增、更新与删除的文件输出为 Upsert 语义的实时表static只考虑运行时刻的已有数据一次性以单个 commit 摄入全部文件后结束。从实现看源码 run 方法两种模式的差异体现在会话类型与循环行为上static使用SessionType.NATIVE会话摄入完一个快照 diff 后立即break退出循环streaming使用SessionType.UPSERT会话循环执行并在每次扫描后time.sleep(refresh_interval)。示例选用static模式非常合理——它让程序在一次性读取后自然结束适合连通性测试而streaming模式会持续轮询适合长期运行的实时管道。format输出表结构binary默认结果表含data列保存每个文件的二进制内容only_metadata只输出_metadata列含路径、大小、时间等元数据不会下载文件内容从而节省时间与流量。源码中该模式通过向 UpsertSession 注入随机合成载荷来触发变更配合table.select(_metadata...)实现源码。recursive是否递归扫描子目录默认True扫描root_path下的所有嵌套目录设为False则只处理指定目录内直接放置的文件。object_size_limit文件大小上限单位字节默认None表示不按大小过滤。超过上限的文件内容不会被下载其元数据中的状态会被标记为STATUS_SIZE_LIMIT_EXCEEDED。with_metadata是否附带元数据列默认False。设为True时输出表会额外增加_metadata列包含path、created_at、modified_at、size、seen_at、status、url等字段其中创建/修改时间为 UNIX 时间戳。需要说明only_metadata格式会自动强制开启该列。refresh_interval扫描间隔默认 30 秒仅streaming模式生效可接受秒数、datetime.timedelta或pw.Duration。max_failed_attempts_in_row连续失败上限默认 8。连续读取失败达到该次数后连接器抛出错误终止设为None则无论凭据是否错误都无限重试。max_backlog_size积压上限默认None不设限。限制任一时刻积压在处理的输入条目数达到上限时暂停读取、处理完部分条目后恢复适用于源端初始爆发式吐出大量数据、需要避免内存尖峰的大规模读取场景。实操运行步骤与结果判定根据示例 README 的说明完整运行流程如下第 1 步填写占位参数。打开 sharepoint_test.py把url、root_path、tenant、client_id、thumbprint、cert_path六个占位符替换为真实值。可对照源码文档字符串中的参考示例python/pathway/xpacks/connectors/sharepoint/init.pytable sharepoint.read( urlhttps://company.sharepoint.com/sites/Datasets, tenantc2efaf1f-8add-4334-b1ca-32776acb61ea, client_idf521a53a-0b36-4f47-8ef7-60dc07587eb2, cert_pathcertificate.pem, thumbprint33C1B9D17115E848B1E956E54EECAF6E77AB1B35, root_pathShared Documents/Data, )如需只读取Datasets/Animals/2023目录且不递归子目录可将root_path改为Datasets/Animals/2023并追加recursiveFalse。第 2 步运行程序。在脚本所在目录执行python sharepoint_test.py第 3 步按需注入许可证。若本机环境已配置 Pathway Scale 许可证则可跳过否则以环境变量方式提供PATHWAY_LICENSE_KEY... python sharepoint_test.py第 4 步判定结果。程序运行结束后检查脚本同目录下生成的contents.txt若其中包含数据行说明认证、授权与目录路径全部配置正确连接成功若文件为空或程序报错则应优先核对五个认证参数的准确性尤其是thumbprint与证书文件的匹配关系、应用对目标站点的授权范围以及root_path是否真实存在且非空。连接成功后contents.txt中的每一行对应一个被读取的 SharePoint 文件由 jsonlines writer 序列化输出通常除database64 编码的文件二进制内容外还会附带引擎侧自动补充的time、diff等列。源码视角一次连接测试背后发生了什么为了让验证更有把握不妨理解连接器在示例脚本启动后的完整内部流程。根据 连接器实现其运行可以拆解为四层认证层_ContextWrapper.context使用with_client_certificate建立带证书认证的ClientContext并立即加载context.web、执行一次查询以确认租户/应用/证书三元组有效调度层_SharePointSubject继承自ConnectorSubject作为数据源主体接入 Pathway在静态模式下以NATIVE会话一次性摄入它还负责把元数据以_metadataJSON 序列化随文件内容一并 Upsert 进表扫描层每次循环由_SharePointScanner.get_snapshot_diff完成——通过web.get_folder_by_server_relative_path(root_path)定位目录再以get_files(recursive)拉取文件清单对每个文件提取path、size、created_at、modified_at等元数据并与上次快照比对得到updated_entries新增/变更与deleted_entries已消失两个 diff文件内容经get_content()拉取容错层所有 SharePoint 查询统一经_execute_with_retries执行源码最多重试QUERY_MAX_ATTEMPTS 5次、间隔QUERY_RETRY_INTERVAL_SECONDS 5秒且重试范围覆盖 HTTP 错误与网络连接错误两类瞬时故障避免一次 DNS 抖动或 socket 重置就让整个测试失败。针对上述容错逻辑仓库还提供了专门的单元测试 python/pathway/xpacks/connectors/tests/test_sharepoint.py其中验证了瞬时失败连接错误或 503会被重试直至成功以及重试次数耗尽后会向调用方抛出错误而非静默返回空结果两个关键行为——这说明连接测试报错时大概率是配置层面的硬性问题而非可自愈的瞬时抖动。集成测试给出的进阶验证视角若希望从最小连通性测试走向更完整的参数化验证可以参照仓库中的真实集成测试 integration_tests/sharepoint/test_sharepoint.py。它展示了生产级用法中如何把凭据与配置解耦sharepoint_connector.read( urlhttps://navalgo.sharepoint.com/sites/ConnectorSandbox, root_pathroot_path, tenantos.environ[SHAREPOINT_TENANT], client_idos.environ[SHAREPOINT_CLIENT_ID], thumbprintos.environ[SHAREPOINT_THUMBPRINT], modestatic, cert_path..., )从中可以确认几个与示例程序互补的细节凭据应通过环境变量注入SHAREPOINT_TENANT、SHAREPOINT_CLIENT_ID、SHAREPOINT_THUMBPRINT证书文件与凭据分离管理避免把密钥写死在脚本里object_size_limit行为可验证超过限制的文件不会下载内容其元数据状态为STATUS_SIZE_LIMIT_EXCEEDED且data为空测试用例only_metadata输出形态可验证该格式下输出行只有_metadata、time、diff三列不包含data列但文件大小仍可从清单中准确上报测试用例recursive语义可验证对仅含嵌套子目录文件的测试目录recursiveFalse时输出 0 行、recursiveTrue时输出 1 行测试用例。这些用例恰好覆盖了示例程序未启用的参数分支可作为你验证连接成功后、继续扩展真实业务管道时的手册。从连通性测试走向真实数据管道连接测试通过意味着最困难的环境配置环节已经打通。在示例基础上可以沿两条主线继续深入切换到流式消费将mode改为默认的streaming或省略该参数并调整refresh_interval连接器便会周期性地把 SharePoint 目录中的新增、修改与删除以实时方式推入 Pathway 表适合持续同步文档库的场景。注意streaming下pw.run()不会自行退出需按业务需要配合合适的输出目标运行。用模板管道替换手写脚本仓库开发者文档的 连接器总览 与 YAML 数据源示例 说明了如何通过配置驱动方式编排数据源安装说明 与 许可证指南 则分别覆盖了运行环境准备与许可证配置帮助你在更大规模下落地 SharePoint → Pathway 的实时数据管道。【免费下载链接】pathwayPython ETL framework for stream processing, real-time analytics, LLM pipelines, and RAG.项目地址: https://gitcode.com/GitHub_Trending/pa/pathway创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表