生成页的连接器方法

使用对象的连接器方法 dataApi 处理绑定到页面的 Power Platform 连接器公开的数据。

注释

连接器方法在共享 dataApi 协定中是可选的。 某些主机未实现它们，因此请在调用方法之前检查是否存在方法。 存在的方法并不意味着页面具有绑定到它的连接器，或者已按预期配置、授权或允许连接、数据集、表或操作。

与操作和函数方法不同，连接器方法在调用失败时拒绝返回的承诺，例如，当无法解析连接引用时，连接未获得授权，并且用户未完成同意提示，或者连接器返回错误状态。 executeConnectorOperation ok: false解决大多数错误状态，但仍拒绝丢失操作、未经完成同意的未授权连接（403）或传输失败。 包装连接器调用。try/catch

方法	Description
createConnectorRow	在指定的连接器表中创建新行。
deleteConnectorRow	从指定的连接器表中删除行。
executeConnectorOperation	调用 REST（操作键）连接器公开的命名操作，例如Office 365 用户。
getConnectorSwagger	检索连接器的 Swagger （OpenAPI） 定义。
getConnectorTableSchema	检索连接器公开的表（也称为实体或列表）的架构。
listConnectorDatasets	列出可用于连接器的数据集。
listConnectorOperations	列出 REST（操作键）连接器公开的操作。
listConnectorTables	列出指定连接器数据集中可用的表。
queryConnectorTable	使用指定选项查询连接器公开的表。
retrieveConnectorRow	从指定的连接器表中检索单个行。
updateConnectorRow	更新指定连接器表中的现有行。

queryConnectorTable 方法

使用指定的选项查询连接器公开的表。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称（例如， sp_shared_sharepointonline）。
dataset	string	包含表的数据集，例如SharePoint网站 URL。
tableName	string	表的内部名称，来自 name 由 listConnectorTables. 返回的属性。 请勿使用显示名称。
options	QueryConnectorTableOptions	用于查询表的选项。

QueryConnectorTableOptions

Name	类型	Description
select	string[]	（推荐）要检索的列名数组。
filter	string	（可选）连接器支持的筛选器表达式。
orderBy	string	（可选）连接器支持的 order-by 表达式。
top	number	（可选）要返回的最大行数。

Returns

包含作结果的 承诺 。 作成功后，promise 将返回一个包含具有以下属性结果的数据表的对象：

Name	类型	Description
rows	Object[]	行数据的数组。
hasMoreRows	boolean	指示是否有更多行可用。

queryConnectorTable 返回单个结果页。 它不返回延续函数，目前不支持提取下一页。 如果为true，hasMoreRows匹配的行数超过返回的行数。 缩小查询范围 filter，或告知用户结果不完整。

queryConnectorTable 示例

if (!dataApi.listConnectorTables || !dataApi.queryConnectorTable) {
  throw new Error("Connector methods aren't available on this page.");
}

const tables = await dataApi.listConnectorTables(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing"
);
const documentsTable = tables.find((table) => table.displayName === "Documents");
if (!documentsTable) {
  throw new Error("The Documents table wasn't found in this dataset.");
}
const documentsTableName = documentsTable.name;

const result = await dataApi.queryConnectorTable(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName,
  {
    select: ["Title", "Modified"],
    top: 50,
  }
);

以下示例假定 documentsTableName 保存表的 name 发件人 listConnectorTables，如上所示。

listConnectorTables 方法

列出指定连接器数据集中可用的表（列表或实体）。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
dataset	string	要列出其表的数据集。

Returns

包含表信息的数组的 promise 。 每个条目都有以下属性：

Name	类型	Description
name	string	表的内部名称。
displayName	string	表的显示名称。

listConnectorTables 示例

const tables = await dataApi.listConnectorTables?.(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing"
);

listConnectorDatasets 方法

列出连接器可用的数据集，例如连接可以访问的SharePoint站点。

Parameters

设置此必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。

Returns

包含数据集信息的数组 的承诺 。 每个条目都有以下属性：

Name	类型	Description
name	string	数据集的内部名称或标识符。
displayName	string	数据集的显示名称。

listConnectorDatasets 示例

const datasets = await dataApi.listConnectorDatasets?.("sp_shared_sharepointonline");

listConnectorOperations 方法

列出连接器 Swagger 定义中定义的操作，不包括标记为内部的操作，按显示名称排序。 此方法最适用于 REST（操作键）连接器，例如Office 365 用户。 对于表格连接器，请使用查询和行方法，而不是此方法列出的操作。

Parameters

设置此必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。

Returns

一个包含操作信息的数组 的承诺 。 每个条目都有以下属性：

Name	类型	Description
name	string	连接器的 Swagger 定义中定义的操作 ID。 将此值传递给 executeConnectorOperation。
displayName	string	用于显示的可读操作名称，例如 Swagger 摘要。 如果未定义摘要，则回退到 name 。

listConnectorOperations 示例

const operations = await dataApi.listConnectorOperations?.("sp_shared_sharepointonline");

getConnectorSwagger 方法

检索连接器的 Swagger （OpenAPI） 定义，该定义描述它公开的操作。 返回的文档总体描述了连接器。 它不包括表格连接器的每表列架构。 用于 getConnectorTableSchema 该信息。

Parameters

设置此必需参数的值。

Name	类型	Description
connectorApiId	string	连接器 API 标识符，例如 /providers/Microsoft.PowerApps/apis/shared_sharepointonline。 此标识符不同于大多数其他连接器方法使用的连接引用逻辑名称（connectorLogicalName）。

Returns

一个 承诺 ，包含连接器的 Swagger 定义作为对象。

getConnectorSwagger 示例

if (!dataApi.getConnectorSwagger) {
  throw new Error("getConnectorSwagger isn't available on this page.");
}

const swagger = await dataApi.getConnectorSwagger(
  "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"
);

getConnectorTableSchema 方法

检索连接器公开的表的架构（列定义）。 连接器定义它返回的架构，它因连接器而异。 不要假定它包含表可能包含的每个动态列。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
dataset	string	包含表的数据集。
tableName	string	表的内部名称，来自 name 由 listConnectorTables. 返回的属性。 请勿使用显示名称。

Returns

包含表架构作为对象的 承诺 。

getConnectorTableSchema 示例

if (!dataApi.getConnectorTableSchema) {
  throw new Error("getConnectorTableSchema isn't available on this page.");
}

const schema = await dataApi.getConnectorTableSchema(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName // from listConnectorTables
);

retrieveConnectorRow 方法

从指定的连接器表中检索单个行。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
dataset	string	包含表的数据集。
tableName	string	表的内部名称，来自 name 由 listConnectorTables. 返回的属性。 请勿使用显示名称。
id	string	要检索的行的 ID。
options	RetrieveConnectorRowOptions	（可选）用于检索行的选项。

RetrieveConnectorRowOptions

Name	类型	Description
select	string[]	（推荐）要检索的列名数组。 如果省略，则不会 $select 发送投影 — 连接器确定要返回哪些列，并且不保证返回行中的每个列。

Returns

包含行数据的 承诺 。

retrieveConnectorRow 示例

if (!dataApi.retrieveConnectorRow) {
  throw new Error("retrieveConnectorRow isn't available on this page.");
}

const row = await dataApi.retrieveConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1"
);

createConnectorRow 方法

在指定的连接器表中创建新行。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
dataset	string	包含表的数据集。
tableName	string	表的内部名称，来自 name 由 listConnectorTables. 返回的属性。 请勿使用显示名称。
row	object	要创建的行数据。

Returns

包含连接器返回的响应正文（如果有）的承诺。 根据连接器，此值可以是创建的行、部分行或无值。

createConnectorRow 示例

if (!dataApi.createConnectorRow) {
  throw new Error("createConnectorRow isn't available on this page.");
}

const newRow = await dataApi.createConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  { Title: "New document" }
);

updateConnectorRow 方法

更新指定连接器表中的现有行。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
dataset	string	包含表的数据集。
tableName	string	表的内部名称，来自 name 由 listConnectorTables. 返回的属性。 请勿使用显示名称。
id	string	要更新的行的 ID。
row	object	要更新的行数据。

Returns

包含连接器返回的响应正文（如果有）的承诺。 根据连接器，此值可以是更新的行、部分行或无值。 若要读取行的当前值，请调用 retrieveConnectorRow。

updateConnectorRow 示例

if (!dataApi.updateConnectorRow) {
  throw new Error("updateConnectorRow isn't available on this page.");
}

const updatedRow = await dataApi.updateConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1",
  { Title: "Updated title" }
);

deleteConnectorRow 方法

从指定的连接器表中删除行。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
dataset	string	包含表的数据集。
tableName	string	表的内部名称，来自 name 由 listConnectorTables. 返回的属性。 请勿使用显示名称。
id	string	要删除的行的 ID。

Returns

包含作结果的 承诺 。 作成功后，它不返回任何值。

deleteConnectorRow 示例

if (!dataApi.deleteConnectorRow) {
  throw new Error("deleteConnectorRow isn't available on this page.");
}

await dataApi.deleteConnectorRow(
  "sp_shared_sharepointonline",
  "https://contoso.sharepoint.com/sites/Marketing",
  documentsTableName, // from listConnectorTables
  "1"
);

executeConnectorOperation 方法

调用 REST（操作键）连接器公开的命名操作，例如 HTTP、Teams 发送消息或Office 365 用户。 表格连接器应改用查询和行 CRUD 方法。

Parameters

设置这些必需参数的值。

Name	类型	Description
connectorLogicalName	string	绑定到页面的连接引用的逻辑名称。
operationName	string	连接器的 Swagger 定义中定义的操作 ID。
parameters	object	操作所需的参数。 如果操作不采用任何参数，则传递空对象 （{}）， 即使没有要发送任何参数，也需要此参数。

Returns

包含具有这些属性的操作结果的 承诺 。 如果无法解析连接引用，则承诺将拒绝，无法检索连接器的 Swagger 定义、找不到操作、无法调度调用或未授权连接（HTTP 403），并且用户未完成连接同意提示。

Name	类型	Description
ok	boolean	true 当基础 HTTP 状态小于 400 时。 此状态包括重定向（3xx）状态，因此不要单独视为 ok 操作返回的数据证明，也检查 status 或检查 body。
status	number	连接器返回的原始 HTTP 状态代码。
body	unknown	分析的 JSON 响应正文;如果正文不是 JSON，则为原始字符串。

executeConnectorOperation 示例

以下示例假定名为 CopyFile 接受 sourceUrl 和 destinationUrl 参数的操作。 根据连接器自己的 Swagger 定义（例如，使用 listConnectorOperations 或 getConnectorSwagger）验证操作 ID 及其参数，因为可用操作及其参数因连接器而异。

if (!dataApi.executeConnectorOperation) {
  throw new Error("executeConnectorOperation isn't available on this page.");
}

try {
  const result = await dataApi.executeConnectorOperation(
    "sp_shared_sharepointonline",
    "CopyFile",
    { sourceUrl: "/sites/Marketing/Shared Documents/file.docx", destinationUrl: "/sites/Sales/Shared Documents/file.docx" }
  );

  if (result.ok) {
    console.log(result.body);
  }
  else {
    console.log(result.status);
  }
}
catch (error) {
  console.log(error);
}