跳转到内容
AutomaDocAutomaDoc

Power Automate 和 Power Apps

AutomaDoc 连接器把您的模板带入 Microsoft 的工作流工具。流发送模板占位符的值（来自 SharePoint 列表项、Dataverse 行、Excel 行或表单回复），并取回完成的文档，可直接保存到文档库、作为邮件附件发送，或发布到 Teams。

它适用于 Power Automate、Power Apps（通过流）、Azure Logic Apps 和 Copilot Studio。它基于文档 API 构建，因此 API 对您数据的所有处理（名称、循环、图片、条件）在这里完全相同。

开始之前

Section titled “开始之前”
  1. 一个模板。 在企业门户的模板下、Excel 加载项或飞书多维表格插件中创建，模板中包含 {Customer}、{Invoice_No} 这样的占位符或 {#Items}…{/Items} 循环。连接器会为每个占位符显示一个输入项，读取自模板最近一次上传的文件。
  2. 一个公司 API 密钥。 由贵公司的管理员在企业门户的公司 → API 密钥下创建。它以 amk_ 开头，只显示一次：请把它复制到安全的地方。（模板自己的密钥无法列出您的模板，因此连接器需要公司密钥。）

添加连接器

Section titled “添加连接器”

在 AutomaDoc 连接器出现在认证连接器中之前，请将其作为自定义连接器添加到您的环境中。每个 Power Platform 环境只需添加一次。

  1. 获取连接器的定义。可以下载 下载连接器定义，或使用它的地址：https://api.automadoc.cc/api/v1/power-platform.swagger.json
  2. 在 Power Automate 中打开 Data → Custom connectors（或 More → Discover all → Custom connectors），选择 New custom connector，然后选择 Import an OpenAPI file（您下载的文件）或 Import an OpenAPI from URL（粘贴地址）。将其命名为 AutomaDoc，然后选择 Continue。
  3. General 选项卡会根据定义自动填写（主机、基本 URL 和说明），无需更改。
  4. 在 Security 选项卡中，确认身份验证类型为 API Key，参数名称为 X-Webhook-API-Key，位置为 Header（这些都随定义一起提供）。如果参数标签为空，请输入 API Key。选择 Create connector。
  5. 在 Test 选项卡中选择 New connection，粘贴公司 API 密钥并创建连接。测试 ListTemplates 操作：它会以 200 返回您的模板。

在流程中添加操作并搜索 AutomaDoc：它列在您的自定义连接器中。认证连接器上架后，添加操作时搜索 AutomaDoc，并在要求连接时粘贴密钥即可。

如果您组织的数据丢失防护（DLP）策略阻止自定义连接器，Power Platform 管理员可以按主机 api.automadoc.cc 允许此连接器。企业门户的 Power Automate 页面也提供同样的步骤和下载。

示例：为每个新的 SharePoint 项生成一份文档

Section titled “示例：为每个新的 SharePoint 项生成一份文档”

此流会在 SharePoint 列表新增项时生成一张发票，并将 PDF 保存到文档库。

  1. 触发器。 创建一个自动化云端流，使用 SharePoint → When an item is created，并选择您的站点和列表（例如 Invoices）。
  2. 生成文档。 添加 AutomaDoc → Generate a document。
    • Template：从列表中选择您的发票模板。
    • 模板的输入项会显示在下方。从触发器的动态内容中逐一映射：Invoice_No ← Title、Customer ← Customer、Total ← Amount，依此类推。
    • Output Format：pdf。 该步骤会等到文档就绪，然后把 Document ID、File Name、Status 和 Download URL 交给后续步骤。
  3. 下载文档。 添加 AutomaDoc → Download document，其中 Document ID ← 上一步的 Document ID。
  4. 保存文档。 添加 SharePoint → Create file：
    • Folder Path：您的文档库，例如 /Shared Documents/Invoices。
    • File Name：Generate a document 输出的 File Name。
    • File Content：Download document 输出的 File Content。
  5. 保存流，并在列表中添加一项。几秒钟后 PDF 就会出现在文档库中。

如需改为通过邮件发送，请使用 Office 365 Outlook → Send an email (V2) 并添加附件：名称为 File Name，内容为 File Content。

更多现成的流（用于审批、Microsoft Forms 回复，或把文件附加到列表项）请参见 Power Automate 示例。

明细项：模板中的循环

Section titled “明细项：模板中的循环”

模板中的 {#Items}…{/Items} 表格行会显示为一个列表输入项 Items，每列对应一个字段。要从另一个列表（例如发票的明细行）填充它，请将该输入项切换到 entire array 模式，并传入一个以列名为键的对象数组，例如用 Data Operation → Select 从 Get items 构建：

Select：映射键 值
Product Title
Qty Quantity
Price UnitPrice

从 Dataverse 或 Excel 生成

Section titled “从 Dataverse 或 Excel 生成”

触发器之后的步骤相同，只有触发器和动态内容不同：

  • Dataverse：When a row is added, modified or deleted（更改类型为 Added），然后把行的列映射到模板的输入项。
  • Excel Online (Business)：For a selected row（从 Excel 中运行），或 List rows present in a table 后接 Apply to each：每行执行一次 Generate a document，即每行生成一份文档。

多行合成一份文档

Section titled “多行合成一份文档”

设置为多条记录生成一份文档的模板（列表、每条记录一页、标签）接收的是一个列表：其输入项为 Records，每行一项，该步骤会用所有行生成一份文档。与明细项一样，将 List rows 或 Get items 的行通过 Select 传入。每份文档最多 500 行。

Power Apps

Section titled “Power Apps”

在流中生成文档，然后从应用中调用该流：

  1. 创建一个使用 Power Apps (V2) 触发器的即时云端流，并为应用发送的值添加文本输入。
  2. 添加 Generate a document 并映射这些输入；最后添加 Respond to a Power App or flow，返回 Download URL（或像上文那样保存文件并返回其链接）。
  3. 在应用中通过按钮调用：Set(doc, GenerateInvoice.Run(txtCustomer.Text, txtTotal.Text)); Launch(doc.downloadurl)。

流会等待文档生成。直接调用连接器的应用不会等待：它取回的文档仍处于 processing 状态，需要反复调用 Get document status，直到文档完成。

Logic Apps 和 Copilot Studio

Section titled “Logic Apps 和 Copilot Studio”

同一个连接器也适用于 Logic Apps（标准版和消耗版），操作完全相同。在 Copilot Studio 中，将 Generate a document 添加为智能体的工具：智能体会根据对话填充模板的输入项，并可以把 Download URL 交给用户。

生成步骤如何等待

Section titled “生成步骤如何等待”

Generate a document 使用 Microsoft 工作流工具会自动遵循的轮询模式：请求以 202 Accepted 响应，并附带一个可轮询的链接，平台每 5 秒读取一次，直到文档完成，然后带着完成的文档继续执行。文档生成失败会使该步骤失败，原因（例如从未闭合的循环、无法获取的图片）会显示在步骤的输出中。失败的文档绝不会被当作文件传给下一步：Get document status 和 Download document 对它同样会失败（DOCUMENT_FAILED）。

如果关闭该步骤的 Asynchronous pattern 设置，它会立即返回，此时文档仍处于 processing 状态。添加 Get document status 并传入 Document ID：它会以同样的方式等待文档。如果该步骤的异步模式也关闭了，它会立即响应；此时请自行使用 Do until 等待 Status 不再是 processing，其中包含 Delay（5 秒）和 Get document status。文档失败时，Get document status 也会失败（422），因此循环会因该错误而停止，永远读不到 failed：请在下一个步骤上用 Configure run after（has failed）处理，或者把循环放进 Scope 中。

限制

Section titled “限制”
  • 每个模板每分钟 60 个请求，每个公司每分钟 600 份文档，与文档 API 和 HTTP 触发器共享；每个公司每分钟 60 次模板列表请求；每份文档每分钟 60 次状态查询和 60 次下载。超出限制时，该步骤会返回 429，由平台的重试策略再次尝试。
  • 图片输入必须是公开的网址（https:// 或 http://）。需要登录的 SharePoint 或 OneDrive 链接无法获取；请用公开链接共享图片，或将其托管在其他地方。
  • 文档的保留时间与贵公司保留生成文档的时间相同（由套餐决定）。请在同一个流中下载文件，而不是保存链接。
  • 发送文档签署以及在 PDF 中附加文件可以通过文档 API 使用，但不作为连接器的输入项提供。

疑难排查

Section titled “疑难排查”
您看到的情况 原因
模板列表为空，或连接失败并返回 COMPANY_KEY_REQUIRED 连接使用的是模板自己的密钥；请使用公司 API 密钥创建连接
某个占位符没有输入项 输入项来自模板最近一次上传的文件；请重新上传模板
QUOTA_EXCEEDED 本月已没有剩余文档；请购买文档包或席位
步骤失败并返回 DOCUMENT_FAILED 文档无法生成；步骤的输出会说明原因
Download document 失败并返回 DOCUMENT_NOT_READY 生成步骤的异步模式已关闭，因此文档仍在生成中；请在下载前添加 Get document status

其他所有拒绝情况及其原因都列在文档 API 参考中。