尧图网页设计 
DataHub API 教程模板指南从占位符到可执行示例的功能文档编写规范【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文围绕开源仓库 datahub 中 docs/_api-guide-template.md 这一文档模板展开系统讲解 DataHub 官方 API 教程Tutorial的标准结构、章节语义、多语言示例Tabs组织方式与内联代码引用规范。仓库的 docs/api/tutorials/ 目录下所有面向开发者的 API 教程均以此模板为骨架生成读者通过本文可以掌握 DataHub 教程文档的编写约定理解其 GraphQL / Curl / Python / CLI 四种示例形态如何配合并学会用模板组织一篇结构完整、可验证、可运行的 API 功能指南。模板在文档体系中的定位在 datahub 仓库的docs/目录下官方维护了两套文档模板服务于两种不同粒度的内容模板文件面向内容目标读者docs/_api-guide-template.mdAPI 操作教程Tutorial如何用 GraphQL / Curl / Python / CLI 完成某项具体操作调用 API 或使用 SDK 的开发者docs/_feature-guide-template.md功能指南Feature Guide某功能是什么、如何配置、最佳实践与 FAQ使用 DataHub 平台的功能用户两者的关系是互补的功能指南回答What WhyAPI 教程回答How用代码怎么做。模板注释中也明确要求教程正文开头的功能简介段落应以平实语言解释功能本身并链接到功能指南获取更详细信息。从实际产出来看docs/api/tutorials/ 目录下的 tags.md、lineage.md、owners.md、datasets.md、domains.md 等数十篇教程全部遵循_api-guide-template.md的章节骨架是理解该模板的最佳实体样本。模板核心章节逐段解析_api-guide-template.md文件本体以 HTML 注释承载写作指引、以占位符如[Feature Name]标记待填充内容其结构可还原为如下固定骨架# [Feature Name] 一段平实语言的功能定义 指向功能指南的链接 ### Goal of This Guide 本教程要达成的操作目标列表 ## Prerequisites 部署 Quickstart、摄取示例数据等前置条件 ## [Action] [Feature Name] 每个操作一个小节动宾短语命名 Tabs TabItem valueGraphQL…/TabItem TabItem valueCurl…/TabItem TabItem valuePython…/TabItem TabItem valueCLI…/TabItem /Tabs ### Expected Outcome of [Action] [Feature Name] 演示操作后的预期结果UI 截图或 CLI 输出1. H1 标题与功能简介标题使用[Feature Name]占位实际编写时直接写功能名如# Lineage、# Tags。标题之下必须有一段平实语言的功能定义模板注释给出了两个自检问题该功能的简短定义是什么它为什么有用这段简介不应长篇大论它的职责是让读者快速判断这篇教程是否与我的需求相关并通过链接指向更详细的 功能指南。2. Goal of This Guide目标清单模板要求用项目符号列出本教程的主要操作目标actions例如Add lineage between datasetsAdd column-level lineage between datasetsRead lineage (upstream or downstream) for a given entitytags.md 的做法是把目标的动词显式标出Create: create a tag.、Read: read tags attached to a dataset.、Add: add a tag to a column of a dataset or a dataset itself.、Remove: remove a tag from a dataset.。这形成了一种Create / Read / Add / Remove四段式组织法后续每个小节逐一兑现清单中的目标。3. Prerequisites前置条件模板对前置条件的指引是部署 DataHub Quickstart 并摄取示例数据然后链接到 DataHub Quickstart Guide。同时要求列出教程专属的额外准备例如需要特定版本的 CLI或用:::note提示性内容强调关键前置约束。tags.md 中的实践极具参考价值——它在 Prerequisites 中加入了如下注意块Before modifying tags, you need to ensure the target dataset is already present in your DataHub instance. If you attempt to manipulate entities that do not exist, your operation will fail. In this guide, we will be using data from sample ingestion.这类提示的意义在于API 教程的操作对象实体 URN必须已存在于实例中否则操作会失败。凡是依赖已有实体的教程都应显式声明这一约束并说明教程使用的数据来源通常是示例摄取数据。Tabs 多语言示例规范GraphQL / Curl / Python / CLI模板的核心约定是每个操作小节都必须提供统一格式的代码片段与预期结果并使用 Docusaurus 的Tabs/TabItem组件组织四种语言形态。真实教程通过文件头import Tabs from theme/Tabs;与import TabItem from theme/TabItem;引入组件见 tags.md。GraphQL Tab提供可执行的 GraphQL 查询或变更语句。以 tags.md 中的createTag为例mutation createTag { createTag(input: { name: Deprecated, id: deprecated, description: Having this tag means this column or table is deprecated. }) }模板注释还给出了校验建议如果某操作不支持某种语言形态直接删除对应的 TabItem而不是留空占位。例如纯数据读取类操作在 lineage.md 中同时给出 GraphQL 查询scrollAcrossLineage、searchAcrossLineage等。Curl Tab模板给出了从 GraphQL 查询生成 Curl 片段的标准范式即把整个 query 转义后放入--data-raw并使用 Bearer Token 认证curl --location --request POST http://localhost:8080/api/graphql \ --header Authorization: Bearer my-access-token \ --header Content-Type: application/json \ --data-raw { query: mutation createTag { createTag(input: { name: \Deprecated\, id: \deprecated\,description: \Having this tag means this column or table is deprecated.\ }) }, variables:{}}两个关键占位my-access-token指 Personal Access Token 中生成的令牌http://localhost:8080/api/graphql是本地 Quickstart 的 GraphQL 端点。关于 GraphQL 环境准备的完整说明见 how-to-set-up-graphql.md。Python Tab模板要求 Python 片段统一放在metadata-ingestion/examples/library/目录下并在教程中使用内联引用指令引入形式为{{ inline /metadata-ingestion/examples/library/file_name.py show_path_as_comment }}这是本模板最具约束力的规范之一——教程正文不直接粘贴 Python 代码而是通过内联引用指向仓库中的可运行示例文件从而保证文档代码与源码同步、可直接运行。该目录下的真实示例包括tag_create.py创建基础 tag 与带完整属性的 tag并调用client.entities.upsert()写入dataset_add_tag.py先client.entities.get()获取 dataset再dataset.add_tag()后client.entities.update()回写dataset_query_tags.py读取 dataset 的 tags 并打印lineage_dataset_add.py 等 lineage 系列示例由 lineage.md 引用这些示例统一使用DataHubClient.from_env()建立连接对应的服务端地址与令牌配置可以从环境变量注入示例代码本身无需改动即可在用户环境中运行。CLI Tab提供datahubCLI 命令片段。模板注释要求能用 GraphQL 表达的操作若 CLI 也支持则补上 CLI Tab不支持则删除。owners.md 提供了很好的 CLI 实践datahub user upsert -f user.yaml datahub group upsert -f group.yaml并配合本地 YAML 文件定义用户/组的元数据id、first_name、email、slack、groups、owners、members 等字段。Expected Outcome预期结果验证模板要求每个操作小节后跟随### Expected Outcome of [Action] [Feature Name]用于演示操作成功后的可观察结果。模板注释指出一般情况下应包含 DataHub UI 截图也可以是 CLI 命令的输出等。仓库教程中出现了两种互补的验证方式UI 截图如 tags.md 中创建、添加、移除 Tag 后的界面状态程序化验证用datahubCLI 查询 aspect 来核对元数据是否写入成功。例如 tags.md 在创建 Tag 后用datahub get --urn urn:li:tag:deprecated --aspect tagProperties验证结果{ tagProperties: { description: Having this tag means this column or table is deprecated., name: Deprecated } }移除 Tag 后则用--aspect globalTags核对期望输出tags: []。这种操作 预期输出的闭环设计让读者不仅能照着写代码还能自行验证操作是否生效也是教程可被自动化测试复用的关键。从模板到实战以 Lineage 教程为例看骨架落地lineage.md 是模板骨架在复杂功能上的完整落地样本其小节结构清晰对应模板约定简介段说明 Python SDK 的 lineage 能力表级/列级 lineage、SQL 推理、读取与过滤Getting Started安装acryl-datahub、用DataHubClient(server..., token...)建立连接Add Lineage细分为实体级、列级模糊/严格/自定义映射、SQL 推断、查询节点query node四种添加方式Get Lineage按 hop 数遍历、按列查询、结构化过滤FAQ以问答形式补充边界说明如提供 transformation_text 不会自动产生列级 lineage。模板中每个 Action 配 Tabs 与 Expected Outcome的要求在 lineage 教程中以返回类型定义 代码块的形式体现——它用LineageResult与LineagePath的示例返回结构替代截图演示了模板允许的CLI 输出/返回结构这一预期结果形态。此外它还维护了Supported Lineage Combinations与Column Lineage Options两张参数表后者完整列出False/True/auto_fuzzy/auto_strict/ 列映射字典五种取值及其语义属于模板注释中其他需要解释的说明的合理扩展。编写一份合规教程的检查清单综合模板注释与真实教程可将编写规范归纳为以下自检项结构完整简介 → Goal → Prerequisites → 若干 Action 小节 → Expected Outcome顺序不可颠倒目标驱动每个 H2 小节以动词开头、以功能名结尾如 Add Lineage、Create Tags与 Goal 清单一一对应示例四件套GraphQL / Curl / Python / CLI 中凡功能支持的语言形态都应提供不支持的形态删除对应 TabItem禁止留空Python 一律内联引用代码放在 metadata-ingestion/examples/library/ 下正文用{{ inline ... show_path_as_comment }}引入确保可运行且与源码同步前置条件显式化依赖已有实体的操作必须用:::note声明实体不存在则操作失败结果可验证每个操作后给出 UI 截图或 CLI 输出/返回结构形成闭环链接规范指向 Quickstart、GraphQL 设置、功能指南等关联文档的相对链接应换算为相对仓库根目录的路径如 docs/quickstart.md、docs/api/graphql/how-to-set-up-graphql.md避免局部相对路径导致解析失效。扩展阅读与相关资源模板文件本体docs/_api-guide-template.md、docs/_feature-guide-template.md完整教程集合docs/api/tutorials/tags、lineage、owners、domains、datasets、structured-properties 等Python 可运行示例库metadata-ingestion/examples/library/前置环境准备DataHub Quickstart Guide、how-to-set-up-graphql.md、token-management.mdGraphQL 最佳实践graphql-best-practices.md对于希望为 DataHub 贡献 API 教程或需要在自己的文档站点复用该文档组织方式的团队这份模板的价值在于它把教程文档这一易流于随意的文体固化为可复用、可校验的工程规范从而保证每一篇教程都具备一致的章节结构、四语言示例覆盖与可验证的结果闭环。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub API 教程模板指南：从占位符到可执行示例的功能文档编写规范
DataHub API 教程模板指南从占位符到可执行示例的功能文档编写规范【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文围绕开源仓库 datahub 中 docs/_api-guide-template.md 这一文档模板展开系统讲解 DataHub 官方 API 教程Tutorial的标准结构、章节语义、多语言示例Tabs组织方式与内联代码引用规范。仓库的 docs/api/tutorials/ 目录下所有面向开发者的 API 教程均以此模板为骨架生成读者通过本文可以掌握 DataHub 教程文档的编写约定理解其 GraphQL / Curl / Python / CLI 四种示例形态如何配合并学会用模板组织一篇结构完整、可验证、可运行的 API 功能指南。模板在文档体系中的定位在 datahub 仓库的docs/目录下官方维护了两套文档模板服务于两种不同粒度的内容模板文件面向内容目标读者docs/_api-guide-template.mdAPI 操作教程Tutorial如何用 GraphQL / Curl / Python / CLI 完成某项具体操作调用 API 或使用 SDK 的开发者docs/_feature-guide-template.md功能指南Feature Guide某功能是什么、如何配置、最佳实践与 FAQ使用 DataHub 平台的功能用户两者的关系是互补的功能指南回答What WhyAPI 教程回答How用代码怎么做。模板注释中也明确要求教程正文开头的功能简介段落应以平实语言解释功能本身并链接到功能指南获取更详细信息。从实际产出来看docs/api/tutorials/ 目录下的 tags.md、lineage.md、owners.md、datasets.md、domains.md 等数十篇教程全部遵循_api-guide-template.md的章节骨架是理解该模板的最佳实体样本。模板核心章节逐段解析_api-guide-template.md文件本体以 HTML 注释承载写作指引、以占位符如[Feature Name]标记待填充内容其结构可还原为如下固定骨架# [Feature Name] 一段平实语言的功能定义 指向功能指南的链接 ### Goal of This Guide 本教程要达成的操作目标列表 ## Prerequisites 部署 Quickstart、摄取示例数据等前置条件 ## [Action] [Feature Name] 每个操作一个小节动宾短语命名 Tabs TabItem valueGraphQL…/TabItem TabItem valueCurl…/TabItem TabItem valuePython…/TabItem TabItem valueCLI…/TabItem /Tabs ### Expected Outcome of [Action] [Feature Name] 演示操作后的预期结果UI 截图或 CLI 输出1. H1 标题与功能简介标题使用[Feature Name]占位实际编写时直接写功能名如# Lineage、# Tags。标题之下必须有一段平实语言的功能定义模板注释给出了两个自检问题该功能的简短定义是什么它为什么有用这段简介不应长篇大论它的职责是让读者快速判断这篇教程是否与我的需求相关并通过链接指向更详细的 功能指南。2. Goal of This Guide目标清单模板要求用项目符号列出本教程的主要操作目标actions例如Add lineage between datasetsAdd column-level lineage between datasetsRead lineage (upstream or downstream) for a given entitytags.md 的做法是把目标的动词显式标出Create: create a tag.、Read: read tags attached to a dataset.、Add: add a tag to a column of a dataset or a dataset itself.、Remove: remove a tag from a dataset.。这形成了一种Create / Read / Add / Remove四段式组织法后续每个小节逐一兑现清单中的目标。3. Prerequisites前置条件模板对前置条件的指引是部署 DataHub Quickstart 并摄取示例数据然后链接到 DataHub Quickstart Guide。同时要求列出教程专属的额外准备例如需要特定版本的 CLI或用:::note提示性内容强调关键前置约束。tags.md 中的实践极具参考价值——它在 Prerequisites 中加入了如下注意块Before modifying tags, you need to ensure the target dataset is already present in your DataHub instance. If you attempt to manipulate entities that do not exist, your operation will fail. In this guide, we will be using data from sample ingestion.这类提示的意义在于API 教程的操作对象实体 URN必须已存在于实例中否则操作会失败。凡是依赖已有实体的教程都应显式声明这一约束并说明教程使用的数据来源通常是示例摄取数据。Tabs 多语言示例规范GraphQL / Curl / Python / CLI模板的核心约定是每个操作小节都必须提供统一格式的代码片段与预期结果并使用 Docusaurus 的Tabs/TabItem组件组织四种语言形态。真实教程通过文件头import Tabs from theme/Tabs;与import TabItem from theme/TabItem;引入组件见 tags.md。GraphQL Tab提供可执行的 GraphQL 查询或变更语句。以 tags.md 中的createTag为例mutation createTag { createTag(input: { name: Deprecated, id: deprecated, description: Having this tag means this column or table is deprecated. }) }模板注释还给出了校验建议如果某操作不支持某种语言形态直接删除对应的 TabItem而不是留空占位。例如纯数据读取类操作在 lineage.md 中同时给出 GraphQL 查询scrollAcrossLineage、searchAcrossLineage等。Curl Tab模板给出了从 GraphQL 查询生成 Curl 片段的标准范式即把整个 query 转义后放入--data-raw并使用 Bearer Token 认证curl --location --request POST http://localhost:8080/api/graphql \ --header Authorization: Bearer my-access-token \ --header Content-Type: application/json \ --data-raw { query: mutation createTag { createTag(input: { name: \Deprecated\, id: \deprecated\,description: \Having this tag means this column or table is deprecated.\ }) }, variables:{}}两个关键占位my-access-token指 Personal Access Token 中生成的令牌http://localhost:8080/api/graphql是本地 Quickstart 的 GraphQL 端点。关于 GraphQL 环境准备的完整说明见 how-to-set-up-graphql.md。Python Tab模板要求 Python 片段统一放在metadata-ingestion/examples/library/目录下并在教程中使用内联引用指令引入形式为{{ inline /metadata-ingestion/examples/library/file_name.py show_path_as_comment }}这是本模板最具约束力的规范之一——教程正文不直接粘贴 Python 代码而是通过内联引用指向仓库中的可运行示例文件从而保证文档代码与源码同步、可直接运行。该目录下的真实示例包括tag_create.py创建基础 tag 与带完整属性的 tag并调用client.entities.upsert()写入dataset_add_tag.py先client.entities.get()获取 dataset再dataset.add_tag()后client.entities.update()回写dataset_query_tags.py读取 dataset 的 tags 并打印lineage_dataset_add.py 等 lineage 系列示例由 lineage.md 引用这些示例统一使用DataHubClient.from_env()建立连接对应的服务端地址与令牌配置可以从环境变量注入示例代码本身无需改动即可在用户环境中运行。CLI Tab提供datahubCLI 命令片段。模板注释要求能用 GraphQL 表达的操作若 CLI 也支持则补上 CLI Tab不支持则删除。owners.md 提供了很好的 CLI 实践datahub user upsert -f user.yaml datahub group upsert -f group.yaml并配合本地 YAML 文件定义用户/组的元数据id、first_name、email、slack、groups、owners、members 等字段。Expected Outcome预期结果验证模板要求每个操作小节后跟随### Expected Outcome of [Action] [Feature Name]用于演示操作成功后的可观察结果。模板注释指出一般情况下应包含 DataHub UI 截图也可以是 CLI 命令的输出等。仓库教程中出现了两种互补的验证方式UI 截图如 tags.md 中创建、添加、移除 Tag 后的界面状态程序化验证用datahubCLI 查询 aspect 来核对元数据是否写入成功。例如 tags.md 在创建 Tag 后用datahub get --urn urn:li:tag:deprecated --aspect tagProperties验证结果{ tagProperties: { description: Having this tag means this column or table is deprecated., name: Deprecated } }移除 Tag 后则用--aspect globalTags核对期望输出tags: []。这种操作 预期输出的闭环设计让读者不仅能照着写代码还能自行验证操作是否生效也是教程可被自动化测试复用的关键。从模板到实战以 Lineage 教程为例看骨架落地lineage.md 是模板骨架在复杂功能上的完整落地样本其小节结构清晰对应模板约定简介段说明 Python SDK 的 lineage 能力表级/列级 lineage、SQL 推理、读取与过滤Getting Started安装acryl-datahub、用DataHubClient(server..., token...)建立连接Add Lineage细分为实体级、列级模糊/严格/自定义映射、SQL 推断、查询节点query node四种添加方式Get Lineage按 hop 数遍历、按列查询、结构化过滤FAQ以问答形式补充边界说明如提供 transformation_text 不会自动产生列级 lineage。模板中每个 Action 配 Tabs 与 Expected Outcome的要求在 lineage 教程中以返回类型定义 代码块的形式体现——它用LineageResult与LineagePath的示例返回结构替代截图演示了模板允许的CLI 输出/返回结构这一预期结果形态。此外它还维护了Supported Lineage Combinations与Column Lineage Options两张参数表后者完整列出False/True/auto_fuzzy/auto_strict/ 列映射字典五种取值及其语义属于模板注释中其他需要解释的说明的合理扩展。编写一份合规教程的检查清单综合模板注释与真实教程可将编写规范归纳为以下自检项结构完整简介 → Goal → Prerequisites → 若干 Action 小节 → Expected Outcome顺序不可颠倒目标驱动每个 H2 小节以动词开头、以功能名结尾如 Add Lineage、Create Tags与 Goal 清单一一对应示例四件套GraphQL / Curl / Python / CLI 中凡功能支持的语言形态都应提供不支持的形态删除对应 TabItem禁止留空Python 一律内联引用代码放在 metadata-ingestion/examples/library/ 下正文用{{ inline ... show_path_as_comment }}引入确保可运行且与源码同步前置条件显式化依赖已有实体的操作必须用:::note声明实体不存在则操作失败结果可验证每个操作后给出 UI 截图或 CLI 输出/返回结构形成闭环链接规范指向 Quickstart、GraphQL 设置、功能指南等关联文档的相对链接应换算为相对仓库根目录的路径如 docs/quickstart.md、docs/api/graphql/how-to-set-up-graphql.md避免局部相对路径导致解析失效。扩展阅读与相关资源模板文件本体docs/_api-guide-template.md、docs/_feature-guide-template.md完整教程集合docs/api/tutorials/tags、lineage、owners、domains、datasets、structured-properties 等Python 可运行示例库metadata-ingestion/examples/library/前置环境准备DataHub Quickstart Guide、how-to-set-up-graphql.md、token-management.mdGraphQL 最佳实践graphql-best-practices.md对于希望为 DataHub 贡献 API 教程或需要在自己的文档站点复用该文档组织方式的团队这份模板的价值在于它把教程文档这一易流于随意的文体固化为可复用、可校验的工程规范从而保证每一篇教程都具备一致的章节结构、四语言示例覆盖与可验证的结果闭环。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考