Microsoft Dataverse 节点
使用 Microsoft Dataverse 节点自动处理 Microsoft Dataverse 中的工作,并将其与其他应用程序集成。你可以使用 Dataverse Web API 在标准表和自定义表中创建、读取、更新和删除行。
提示
Credentials 凭据
有关身份验证设置,请参阅 Microsoft Dataverse 凭据。该节点通过 Microsoft Dataverse OAuth2 API 凭据支持委托用户访问和仅应用访问。
Operations 操作
- Row 行
- Create 创建:添加新行。
- Create or Update 创建或更新:使用行 ID 或备用键创建行或更新现有行。
- Delete 删除:删除行。
- Get 获取:按 ID 获取行。
- Get Many 获取多个:获取多行,并可选择筛选和排序。
- Update 更新:更新现有行。此操作不会创建不存在的行。
选择表和行
将 Resource 资源 设为 Row 行,然后选择 Operation 操作。
在 Table Name or ID 表名称或 ID 中选择 From List 从列表中选择,可搜索环境中的表。若要手动输入表,请选择 By ID 按 ID,并输入其 Web API 实体集名称,例如 accounts 或 contacts。请勿输入表的显示名称、单数逻辑名称或 GUID。
对于 Get 获取、Update 更新 和 Delete 删除,使用 Row ID 行 ID 以 From List 从列表中选择 方式选择行,或使用 By ID 按 ID 输入其 GUID。例如,00000000-0000-0000-0000-000000000001 符合所需格式,请将其替换为你环境中某一行的 ID。
只有 Create or Update 创建或更新 支持备用键寻址。
创建和更新行
对于 Create 创建、Update 更新 和 Create or Update 创建或更新,请选择一种 Input Mode 输入模式:
| 输入模式 | 输入值的方式 |
|---|---|
| JSON(默认) | 在 Row Item (JSON) 行数据项 (JSON) 中输入对象。使用列的逻辑名称作为键,并使用列所需的数据类型。 |
| Fields (Key / Value Pairs) 字段(键/值对) | 在 Fields 字段 下选择 Add Field 添加字段,选择 Field Name or ID 字段名称或 ID,然后输入 Field Value 字段值。每一列重复此操作。 |
请至少提供一个字段。节点会拒绝空的行数据项。字段选择器会显示可用于所选操作的可写列。对于 Create or Update 创建或更新,选择器会显示同时支持创建和更新行的列。
Field Value 字段值 输入框是字符串字段。节点不会自动将字面文本转换为数字或布尔值。需要保留这些类型或发送 null 时,请使用 JSON。
创建账户
要创建账户,请选择 Create 创建,将 Table Name or ID 表名称或 ID 设为 accounts,并使用 JSON 输入。在 Row Item (JSON) 行数据项 (JSON) 中输入以下对象:
{
"name": "Contoso",
"accountnumber": "ACC-001",
"numberofemployees": 25,
"creditonhold": false
}
对于 Update 更新,选择现有账户的 Row ID 行 ID,并只发送要更改的字段。例如,{"telephone1": "555-0100"} 会更新电话号码,而不会替换其他字段。
设置查找列
查找列引用另一个表中的行。当节点可以访问关系 metadata 时,会将查找值转换为 Dataverse 所需的导航属性绑定。
| 查找类型 | 要提供的值 |
|---|---|
单个目标表,例如账户上的 primarycontactid |
行 GUID,或 /contacts(<contact-id>) 这样的引用。 |
| 多个目标表,例如 Customer 列 | /accounts(<account-id>) 或 /contacts(<contact-id>) 这样的明确引用。单独的 GUID 存在歧义。 |
| Owner 列 | /systemusers(<user-id>) 或 /teams(<team-id>)。单独的 GUID 存在歧义。 |
请将尖括号占位符替换为环境中的行 GUID。这些引用可以省略开头的斜杠。
例如,要设置账户的主要联系人和所有者,请在 Row Item (JSON) 行数据项 (JSON) 中包含以下字段:
{
"primarycontactid": "/contacts(<contact-id>)",
"ownerid": "/systemusers(<user-id>)"
}
也可以提供明确绑定,例如 {"[email protected]": "/contacts(<contact-id>)"}。节点会原样传递明确绑定。请使用表 metadata 中区分大小写的准确导航属性名称,该名称可能与列的逻辑名称不同。
要清除单目标查找,请发送 null,例如 {"primarycontactid": null}。对于多表查找,如果 Dataverse 允许清除该关系,请改为清除对应的特定导航属性。
创建或更新行
选择 Create or Update 创建或更新,使用以下任一 Identifier Type 标识符类型 指定行:
- Row ID (GUID) 行 ID (GUID):选择或输入 Row ID 行 ID。如果该行不存在,Dataverse 会使用此 GUID 创建它。
- Alternate Key 备用键:输入 Alternate Key Predicate 备用键谓词,例如
accountnumber='ACC-001'。使用前,请先在 Dataverse 中为该表配置备用键。
只输入谓词,不要包含表名称或外围括号。对于字符串键,请保留值两侧的单引号。节点会拒绝谓词中的 URL 分隔符、路径分隔符和控制字符。
在 Options 选项 下,使用 Behavior 行为 控制写入方式:
| 行为 | 结果 |
|---|---|
| Create or Update 创建或更新(默认) | 如果行不存在则创建,存在则更新。 |
| Update Only 仅更新 | 更新现有行。如果行不存在则失败。 |
| Create Only 仅创建 | 创建新行。如果行已存在则失败。 |
例如,选择 accounts 表,选择 Alternate Key 备用键,然后输入 accountnumber='ACC-001'。在 Row Item (JSON) 行数据项 (JSON) 中发送 {"name": "Contoso"},即可创建或更新具有该账户编号的账户。
查询行
Get 获取 操作在 Options 选项 下支持 Select Column Names or IDs 选择列名称或 ID 和 Expand Query 展开查询。Get Many 获取多个 还支持其他筛选、排序和结果数量限制。
使用 OData 获取多行
选择 Get Many 获取多个,并配置以下参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
| Return All 返回全部 | 关闭 | 持续跟随 OData 分页链接,直到没有更多结果。 |
| Limit 限制 | 50 |
Return All 返回全部 关闭时返回的最大行数,最小值为 1。 |
| Select Column Names or IDs 选择列名称或 ID | 未选择 | 选择要检索的列。留空则使用 Dataverse 的默认投影。 |
| Filter Rows 筛选行 | 空 | OData 筛选表达式,例如 statecode eq 0。不要包含 $filter= 前缀。 |
| Expand Query 展开查询 | 空 | 用于检索相关行的 OData 表达式,例如 primarycontactid($select=fullname)。 |
| Sort Column Name or ID 排序列名称或 ID | 未选择 | 用于排序的列。 |
| Sort Direction 排序方向 | Ascending 升序 | 所选列的排序方向。 |
| Sort By Override 排序覆盖 | 空 | 原始 OData 排序表达式,例如 createdon desc, name asc。仅在 Sort Column Name or ID 排序列名称或 ID 为空时使用。 |
| Row Count ($Top) 行数 ($Top) | 未设置 | 服务端结果上限。覆盖从 Limit 限制 推导出的 $top 值,并禁用服务器驱动的分页。 |
例如,要检索最多 100 个名称以 Contoso 开头的活跃账户:
- 将 Table Name or ID 表名称或 ID 设为
accounts。 - 保持 Return All 返回全部 关闭,并将 Limit 限制 设为
100。 - 在 Options 选项 下的 Select Column Names or IDs 选择列名称或 ID 中选择
name和accountnumber。 - 将 Filter Rows 筛选行 设为
statecode eq 0 and startswith(name,'Contoso')。 - 将 Sort Column Name or ID 排序列名称或 ID 设为
name,将 Sort Direction 排序方向 设为 Ascending 升序。
读取列选择器会自动使用 _primarycontactid_value 这样的查找属性名称。编写原始筛选或排序表达式时,请对查找 GUID 使用这种属性形式。例如,使用 _primarycontactid_value eq <contact-id> 进行筛选,并将 <contact-id> 替换为不带引号的 GUID。Expand Query 展开查询 应使用导航属性名称。
分页和结果数量限制
对于 OData 查询,节点会跟随 @odata.nextLink,直到达到 Limit 限制 或检索到所有可用结果。
当 Limit 限制 不超过 5,000 时,节点也会将其作为 $top 发送。对于更大的限制,节点不会设置 $top,以便 Dataverse 返回多页结果。明确设置的 Row Count ($Top) 行数 ($Top) 优先级更高,即使启用 Return All 返回全部,也可能限制结果数量。
要检索超过 5,000 行,请不要设置 Row Count ($Top) 行数 ($Top),并启用 Return All 返回全部 或将 Limit 限制 设为大于 5,000。这些分页规则适用于 OData 查询,不适用于 FetchXML。
使用 FetchXML
设置 Options 选项 > FetchXML Query 以运行 FetchXML 查询。它会取代 OData 的选择、筛选、排序、展开和 top 选项。保持 Return All 返回全部 关闭,并设置 Limit 限制 以限制返回行数。
例如,选择 accounts 表并输入以下查询,可检索最多 50 个活跃账户:
<fetch top="50">
<entity name="account">
<attribute name="name" />
<attribute name="accountnumber" />
<filter>
<condition attribute="statecode" operator="eq" value="0" />
</filter>
</entity>
</fetch>
FetchXML 使用表的逻辑名称 account,而 Table Name or ID 表名称或 ID 使用实体集名称 accounts。
警告
FetchXML 分页
Microsoft Dataverse 节点不支持 FetchXML 分页。将 FetchXML Query 与 Return All 返回全部 一起使用会产生错误。关闭 Return All 返回全部 可避免该错误,但提高 Limit 限制 也不会检索更多 FetchXML 页面。需要自动分页时,请使用 OData 查询。
使用弹性表
对于 Get 获取、Get Many 获取多个 和 Delete 删除,如需针对弹性表分区,请设置 Options 选项 > Partition ID 分区 ID。
Create 创建、Update 更新 和 Create or Update 创建或更新 不提供 Partition ID 分区 ID 选项。使用 Create 创建 创建分区行时,请在行 JSON 中包含 partitionid。
要更新或 upsert 分区行,请使用 Create or Update 创建或更新,并将 Identifier Type 标识符类型 设为 Alternate Key 备用键。在 Alternate Key Predicate 备用键谓词 中包含表的主键和 partitionid:
<primary-key-column>=<row-id>,partitionid='<partition-id>'
请将占位符替换为表的主键列逻辑名称、行 GUID 和分区 ID。如果该行必须已存在,请将 Behavior 行为 设为 Update Only 仅更新。有关特定表的行为和限制,请参阅 Microsoft 的弹性表文档。
输出和 metadata
- Create 创建、Update 更新 和 Create or Update 创建或更新 会在写入后请求该行,并返回 Dataverse 的响应。
- Get 获取 返回单行。
- Get Many 获取多个 会将每行作为单独的 n8n 数据项返回,而不是放在
value字段中的集合。 - Delete 删除 成功后返回
{"success": true, "id": "<row-id>"}。
除 Delete 删除 外,所有操作都提供 Options 选项 > Return Full Metadata 返回完整 metadata,默认关闭。启用后可请求 OData 注释,包括 Dataverse 提供的格式化值。节点不会重命名列或简化注释。
常见问题
无法加载表或列选项
检查选择器中显示的 HTTP 状态和 Dataverse 错误。验证环境 URL 和凭据访问权限,包括对表 metadata 的访问权限。请参阅 Microsoft Dataverse 凭据故障排除。
如果知道表的实体集名称,可以通过 Table Name or ID 表名称或 ID > By ID 按 ID 输入。这样做不会绕过 Dataverse 权限。
查找值被拒绝
不要使用显示名称作为查找值。对于单目标查找,请使用 GUID;对于其他查找,请使用包含实体集名称和行 ID 的引用。Customer 和 Owner 列需要明确指定目标表。示例请参阅设置查找列。
查询返回的行数少于预期
检查 Limit 限制;如果需要分页,请移除 Row Count ($Top) 行数 ($Top),并确认查询是否使用 FetchXML。请参阅分页和结果数量限制和使用 FetchXML。