使用 MCP Toolbox 的 dataplex-get-discovery-results 工具获取 Dataplex 数据发现扫描结果【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxMCP Toolbox本项目为数据库与 Google Cloud 数据服务提供了一整套 MCPModel Context ProtocolServer 工具其中dataplex-get-discovery-results用于在 Dataplex Data Discovery 扫描完成后拉取最终的发现结果发布元数据、扫描文件数、处理字节数等。本指南以 knowledge-catalog-get-discovery-results.md 为骨架结合仓库内源码与预置配置系统讲解该工具的使用前提、参数、配置方式、响应结构及底层实现帮助你或你的 LLM Agent在 Data Discovery 工作流中正确、可靠地拿到扫描产出。工具概述Aboutdataplex-get-discovery-results是一个只读工具用于检索已完成的 Dataplex Data Discovery 扫描的结果。该扫描的作用是自动爬取 Cloud StorageGCS目录中的文件推断其 schema、文件格式如 CSV、JSON、Parquet与分区信息并自动将这些文件注册、发布为 BigQuery 表外部表或 BigLake 表同时把元数据登记到 Dataplex Universal Catalog。本工具返回的正是这一过程的“最终产出”发布元数据被发现的 GCS 表被注册到了哪个 BigQuery dataset审计统计扫描的 GCS 文件数量、总处理字节数以及在 BigQuery 中新建、更新、删除的表数量。对应字段为返回 DataScan 对象中的嵌套公共字段dataDiscoveryResult.bigqueryPublishing与dataDiscoveryResult.scanStatistics。使用本工具有两条必须遵守的规则WARNING在调用本工具之前必须先通过dataplex-get-run-status确认扫描的执行任务已经成功state 为SUCCEEDED否则返回的结果将是空的。CRITICAL返回结果必须通过 DataScan 内嵌套的公共字段dataDiscoveryResult.bigqueryPublishing与dataDiscoveryResult.scanStatistics访问不要依赖顶层受限字段。前置条件IAM 权限要求Knowledge Catalog 使用 Identity and Access Management (IAM) 控制用户和组对资源的访问。MCP Toolbox 在访问 Knowledge Catalog 时会使用你的 Application Default Credentials (ADC) 进行授权和认证。在为你的 server 设置 ADC之外还需要确保 IAM 身份拥有执行相应任务所需的权限。具体请参阅 Knowledge Catalog IAM permissions 与 Knowledge Catalog IAM roles。对于本工具而言至少需要具备读取 Dataplex DataScan 资源的权限例如dataplex.dataScans.get对应的角色建议按最小权限原则授予。Source 配置dataplex-get-discovery-results必须挂载在一个dataplex类型的 source 上。source 的基础配置如下来自 source.mdkind: source name: my-dataplex-source type: dataplex project: my-project-idfieldtyperequireddescriptiontypestringtrue必须为 dataplex。projectstringtrue用于配额与计费的 GCP 项目 ID如 my-project-id。从源码看source 通过ProjectID()与GetDataScan()两个方法支撑本工具的运行见 internal/tools/dataplex/dataplexgetdiscoveryresults/dataplexgetdiscoveryresults.go 中的compatibleSource接口定义。参数说明Parametersdataplex-get-discovery-results接受以下两个参数fieldtyperequireddescriptionscanIdstringtrueDataplex discovery scan 的唯一 ID例如nq-disc-12345。locationstringtrue创建 scan 的 Google Cloud 区域例如us-central1。这两个参数在源码初始化时被注册为字符串参数见 dataplexgetdiscoveryresults.go其中scanId的描述特别注明该 ID 是从创建操作creation operation响应的target或name字段中提取的如nq-disc-12345...。在Invoke方法中若scanId或location为空工具会返回 Agent 错误dataplexgetdiscoveryresults.go因此在编排调用链时务必保证这两个参数非空。配置示例Example在 MCP Toolbox 的配置文件中按如下方式声明该工具kind: tool name: get_discovery_results type: dataplex-get-discovery-results source: my-dataplex-source description: Fetch results of a completed metadata discovery scan.Reference 字段fieldtyperequireddescriptiontypestringtrue必须为 dataplex-get-discovery-results。sourcestringtrue该工具所挂载的 source 名称。descriptionstringtrue传给 LLM 的工具描述。从源码看Config结构体还支持可选的annotations字段dataplexgetdiscoveryresults.go未显式指定 annotations 时工具会默认按只读NewReadOnlyAnnotations标注这与该工具只做查询、不产生副作用的行为一致见 dataplexgetdiscoveryresults.go。该配置的解析行为由单元测试锁定验证dataplexgetdiscoveryresults_test.go测试用一段含kind: tool、name: example_tool、type: dataplex-get-discovery-results、source: my-instance、description: some description的 YAML 作为输入断言解析结果中Type、Source、Description、AuthRequired等字段与预期完全一致。底层实现它如何拉取结果理解实现有助于排查问题。核心调用链如下参数校验Invoke方法先取出scanId与location并做非空校验构造请求调用 source 的GetDataScan(ctx, location, scanId)序列化返回将返回的*dataplexpb.DataScan用protojson.Marshal序列化为 JSON 原始消息返回给调用方dataplexgetdiscoveryresults.go。GetDataScan在 source 端的实现internal/sources/dataplex/dataplex.go为func (s *Source) GetDataScan(ctx context.Context, location, scanID string) (*dataplexpb.DataScan, error) { name : fmt.Sprintf(projects/%s/locations/%s/dataScans/%s, s.ProjectID(), location, scanID) req : dataplexpb.GetDataScanRequest{ Name: name, View: dataplexpb.GetDataScanRequest_FULL, } return s.DataScanClient.GetDataScan(ctx, req) }两点值得注意资源名按projects/{project}/locations/{location}/dataScans/{scanId}拼接其中 project 取自 source 配置location 与 scanId 来自工具参数三者缺一不可请求显式指定View: FULL保证返回的 DataScan 包含完整的发现结果字段即dataDiscoveryResult这正是文档要求访问的嵌套公共字段所在的位置。典型编排流程从触发扫描到获取结果dataplex-get-discovery-results处于一个典型的异步扫描工作流的末端。完整的编排与 discover-metadata.md 描述一致如下触发扫描调用dataplex-discover-metadata传入resourcePath格式//storage.googleapis.com/{bucket_name}与location创建 Data Discovery scan 模板并触发首次异步执行工具返回一个 LRO长时运行操作名称等待模板创建完成用dataplex-get-operation轮询该 LRO直到done为 true从完成操作的响应中提取scanId例如nq-disc-12345轮询执行状态用dataplex-get-run-status参数scanIdlocation可选jobId轮询后台 DataScanJob 的执行状态直到返回的state为SUCCEEDED。典型执行耗时约 2–5 分钟若状态为FAILED请检查错误详情见 get-run-status.md获取结果调用本工具dataplex-get-discovery-results参数scanIdlocation从返回 DataScan 的dataDiscoveryResult.bigqueryPublishing与dataDiscoveryResult.scanStatistics字段读取发布元数据与统计信息。这段工作流在预置配置 internal/prebuiltconfigs/tools/dataplex.yaml 中有完整的中文注释版描述discover_metadata与get_discovery_results两个 tool 的 description 字段见该文件 L197-L234其中明确指出get_discovery_results返回的内容包括——被发现的 GCS 表注册到了哪个 BigQuery dataset、扫描的 GCS 文件数、总处理字节数以及 BigQuery 中新建/更新/删除的表数量。此外该预置配置还定义了名为enrich的 toolsetdataplex.yaml将discover_metadata、get_discovery_results、get_operation、get_run_status等工具打包方便通过 MCP Toolbox 的 toolset 机制一次性暴露完整的“元数据富化”能力。常见问题与注意事项结果为空绝大多数情况下是因为在任务成功前就调用了本工具。务必先轮询dataplex-get-run-status至SUCCEEDED字段访问错误结果必须从dataDiscoveryResult.bigqueryPublishing与dataDiscoveryResult.scanStatistics这两个嵌套公共字段读取不要从 DataScan 顶层或受限字段取数否则会得到空值scanId来源它来自创建操作dataplex-discover-metadata返回的 LRO 完成后的响应而不是用户随意指定的字符串参数为必填缺失时工具会直接报错权限不足确保 IAM 身份具备读取 DataScan 的权限并通过 ADC 正确配置认证。参考文档本工具官方文档knowledge-catalog-get-discovery-results.md配套的状态轮询工具knowledge-catalog-get-run-status.md触发扫描的工具knowledge-catalog-discover-metadata.mdKnowledge Catalog source 配置source.md源码实现dataplexgetdiscoveryresults.go单元测试dataplexgetdiscoveryresults_test.go预置配置与编排说明dataplex.yaml【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考