mcp-toolbox Knowledge Catalog 实战：使用 dataplex-update-data-product-aspects 更新 Data Product 元数据 Aspects

mcp-toolbox Knowledge Catalog 实战使用 dataplex-update-data-product-aspects 更新 Data Product 元数据 Aspects【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolboxdataplex-update-data-product-aspects是 mcp-toolboxMCP Toolbox for Databases为 Knowledge Catalog原 Dataplex提供的一个 MCP 工具用于在一次请求内为已存在的 Data Product Entry 添加或修改多个元数据 Aspect如文档类overview、契约类refresh-cadence。本文以 tools/knowledge-catalog-update-data-product-aspects.md 为骨架结合仓库源码、预置配置与测试用例完整讲解该工具的参数模型、Aspect 对象结构、配置方式、输出格式与底层调用链读完即可在自有环境中配置并通过 LLM 驱动更新数据产品元数据。工具概述在 Knowledge Catalog原 Dataplex中Entry是数据资产的元数据记录容器而丰富的描述性信息如 schema、业务描述、分类等存放在与 Entry 关联的Aspect中Aspect 依据预定义的Aspect Type蓝图创建详见 source.md 中的数据模型说明。dataplex-update-data-product-aspects工具的作用就是操作 Data Product 对应的 Catalog Entry允许你在单个调用里新增或修改多个元数据 Aspect适合 LLM 需要同时更新文档、刷新频率、联系方式等多项元数据的场景。在源码层面该工具通过tools.Register注册为dataplex-update-data-product-aspects类型对应的 Go 包为 dataplexupdatedataproductaspects其中定义了资源类型常量resourceType dataplex-update-data-product-aspects。dataplex.yaml 预置配置中对该工具的官方描述为Updates metadata aspects (like overview or contacts) on an existing Data Product Entry.兼容的数据源Compatible Sources该工具必须运行在兼容的 Data Source 之上。它要求 Source 实现compatibleSource接口即具备以下能力见 dataplexupdatedataproductaspects.goProjectID() string返回当前 GCP 项目 IDProjectNumber() int64返回项目编号用于构造 Entry 全限定名UpdateEntry(ctx, entry, updateMask)调用 Catalog 客户端执行更新。从源码结构可以推断目前只有dataplex类型的 Source 满足该接口。Source 的 YAML 配置方式如下详见 source.mdkind: source name: my-dataplex-source type: dataplex project: my-project-id其中type必须为dataplexproject为用于配额与计费目的 GCP 项目 ID必填。前置要求IAM 权限与身份认证Knowledge Catalog 使用 Identity and Access Management (IAM) 控制用户和组对 Catalog 资源的访问。Toolbox 在与 Knowledge Catalog 交互时会使用你的**应用默认凭据Application Default Credentials, ADC**完成授权与认证。因此除了为你的服务端配置 ADC 之外还必须确保该 IAM 身份被授予了执行目标操作所需的权限并参考 Knowledge Catalog 的 IAM 权限与 IAM 角色文档为身份应用相应权限与角色。若权限不足调用将由util.ProcessGcpError转换为对应的 GCP 错误返回见源码 dataplexupdatedataproductaspects.go。工具参数详解dataplex-update-data-product-aspects接受以下三个参数fieldtyperequireddescriptionlocationIdstringtrueThe location ID (e.g.us,us-central1) of the Data Product.dataProductIdstringtrueThe unique ID of the Data Product.aspectsarray of objectstrueThe list of aspects to add or update on the Data Product Entry. Each object containsprojectId(string, required),locationId(string, required),aspectTypeId(string, required), anddata(object, optional, JSON map of the aspect details).对应到源码 Initialize三个参数被定义为locationIdData Product 所在的区域 ID如us、us-central1dataProductIdData Product 的唯一 IDaspects由aspect元素构成的数组每个元素是一个 Map承载 aspectTypeId 与对应的 payload 细节。在 Invoke 阶段工具会对三个参数逐一做校验locationId、dataProductId必须为非空字符串aspects必须为数组否则返回 Agent 错误例如locationId parameter is required and must be a non-empty string。Aspect 对象字段系统 Aspects 与自定义 Aspectsaspects数组中的每个对象必须包含以下字段projectIdAspect 类型所属的项目 ID。系统 Aspects如overview、refresh-cadence取值为dataplex-types。locationIdAspect 类型所在区域。系统 Aspects如overview、refresh-cadence取值为global。aspectTypeIdAspect 类型的唯一名称如overview或refresh-cadence。data符合该 Aspect 类型 schema 的 JSON 载荷。系统 overview文档类Schema字段类型必填说明contentstringtrue详细文档内容Markdown 或纯文本contentTypestring可选内容类型格式取值MARKDOWN、HTMLlinksarray of objects可选相关 URL 链接列表每个链接对象含urlstring必填与titlestring可选系统 refresh-cadence契约类Schema字段类型必填说明frequencystringtrue数据更新频率取值Daily、Weekly、Monthly、Quarterly、Half-Yearly、YearlyrefreshTimestring可选数据更新的具体时间如09:00 PSTthresholdInMinutesint可选延迟delinquency阈值分钟如15cronSchedulestring可选可选的 cron 调度表达式如0 * * * *源码中的默认值与校验逻辑源码中的Aspect结构体见 dataplexupdatedataproductaspects.go定义了 JSON 字段映射projectId、locationId、aspectTypeId均带validate:requireddata为可选的map[string]any。实际调用时工具会执行以下逻辑L179-L218每个 Aspect 的aspectTypeId与data均不允许为空data为空时返回data is required for aspect at index %d错误默认值兜底若projectId为空且aspectTypeId为overview或refresh-cadence则自动填入dataplex-types否则回退为 Source 的ProjectID()同理若locationId为空系统 Aspect 自动填入global否则回退为参数的locationId。也就是说更新系统 Aspects 时可以省略projectId/locationId每个 Aspect 最终被构造成projects/{projectId}/locations/{locationId}/aspectTypes/{aspectTypeId}形式的完整 Aspect 类型名data通过structpb.NewStruct序列化为 protobuf 结构作为dataplexpb.Aspect写入aspectsMap。配置示例将工具加入 Toolbox 配置YAMLkind: tool name: update_data_product_aspects type: dataplex-update-data-product-aspects source: my-dataplex-source description: Use this tool to update aspects (like overview or contacts) on a Data Product Entry.name工具在 MCP 服务中的调用名可自定义type必须为dataplex-update-data-product-aspectssource指向上面定义的dataplexSourcedescription传给 LLM 的工具说明建议写清楚适用场景帮助模型在恰当的时机调用。该配置的解析行为由单元测试 TestParseFromYamlDataplexUpdateDataProductAspects 覆盖——测试用kind: tooltype: dataplex-update-data-product-aspectssource: my-instance的最小配置验证了 YAML 到Config结构的完整反序列化。此外dataplex.yaml 预置配置中已包含一个可直接启用的工具块name:update_data_product_aspects而集成测试 dataplex_integration_test.go 也注册了my-dataplex-update-data-product-aspects-tool与带authRequired: [my-google-auth]的认证变体说明该工具同样支持接入 Google 认证来源。输出格式工具调用成功后返回更新后的 Catalog Entry 详情与 Aspects{ locationId: us, dataProductId: my-data-product, entrySource: { resource: projects/..., displayName: My Data Product Resource, description: Resource details }, entryType: projects/dataplex-types/locations/global/entryTypes/data-product, aspects: [ { projectId: dataplex-types, locationId: global, aspectTypeId: overview, data: { content: Updated description content } } ] }说明locationId与dataProductId并非返回值本身而是对请求参数的透传回显源码响应结构体UpdateDataProductAspectsResponse仅包含name、entrySource、entryType、aspects四个字段见 dataplexupdatedataproductaspects.go。返回内容各字段含义name更新后的 Entry 全限定名entrySourceEntry 的资源来源信息resource、displayName、description仅在 Catalog 返回时填充entryTypeEntry 的类型Data Product 对应projects/dataplex-types/locations/global/entryTypes/data-productaspects更新后实际生效的 Aspect 列表每个元素包含projectId、locationId、aspectTypeId与data工具将返回的 protobuf Aspect 反向解析为统一的 JSON 结构见 L238-L254。底层调用链与实现原理一次调用在底层经历了如下链路全部位于 dataplexupdatedataproductaspects.go参数解析与校验L147-L172将params.AsMap()中的原始参数经json.Marshal/json.Unmarshal转换为[]Aspect构造 Entry 名称L220-L223按如下模板拼装 Data Product Entry 的完整资源名projects/{projectId}/locations/{locationId}/entryGroups/dataplex/entries/projects/{projectNumber}/locations/{locationId}/dataProducts/{dataProductId}其中projectId、projectNumber来自 SourcelocationId、dataProductId来自请求参数构造 UpdateMaskL230通过fieldmaskpb.New(entry, aspects)生成仅包含aspects字段的更新掩码即本次更新只替换 Entry 的 Aspects不影响其他字段调用 Catalog 客户端source.UpdateEntry(ctx, entry, updateMask)最终在 dataplex.go 中构造dataplexpb.UpdateEntryRequest并调用CatalogClient().UpdateEntry错误经util.ProcessGcpError统一处理结果格式化将返回 Entry 中的 Aspects、EntrySource 等信息重组为上述响应结构。另外需要说明的是与dataplex-create-data-product、dataplex-update-data-product等返回长时操作LRO需要轮询get_operation的流程不同dataplex-update-data-product-aspects通过UpdateEntryAPI同步返回更新后的 Entry调用方无需轮询即可拿到最终结果。Reference工具配置字段fieldtyperequireddescriptiontypestringtrueMust be dataplex-update-data-product-aspects.sourcestringtrueName of the source the tool should execute on.descriptionstringtrueDescription of the tool that is passed to the LLM.相关资源与延伸阅读工具文档knowledge-catalog-update-data-product-aspects.mdData Source 与数据模型说明source.md配套工具创建 Data Product 见 knowledge-catalog-create-data-product.md查询 Data Product 见 knowledge-catalog-get-data-product.md预置配置dataplex.yaml工具实现dataplexupdatedataproductaspects.go单元测试dataplexupdatedataproductaspects_test.goData Source 实现dataplex.go集成测试dataplex_integration_test.go快速上手示例KNOWLEDGE_CATALOG_README.md【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考