生成頁面的連接器方法

使用物件的 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 網站網址。
tableName	string	資料表的內部名稱，取自namelistConnectorTables屬性。 不要使用顯示名稱。
options	QueryConnectorTableOptions	查詢表格的選項。

QueryConnectorTableOptions

Name	類型	Description
select	string[]	（推薦）一組欄位名稱陣列，需取回。
filter	string	（可選）Filter 表達式由連接器支援。
orderBy	string	（可選）連接埠支援的按順序表達式。
top	number	（可選）最多可返回的行數。

Returns

一個包含操作結果的 承諾 。 當操作成功時，承諾會回傳一個包含資料表的物件，結果具有以下屬性：

Name	類型	Description
rows	Object[]	列資料陣列。
hasMoreRows	boolean	表示是否有更多可用列。

queryConnectorTable 返回一頁結果。 它不會回傳延續函數，目前也沒有支援的方法來取得下一頁。 當 hasMoreRows 是 true時，匹配的列數多於返回的列數。 用 縮小查詢 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 保持來自 listConnectorTables的表格name，如上所述。

listConnectorTables 方法

列出指定連接器資料集中可用的表格（清單或實體）。

Parameters

為這些所需參數設定數值。

Name	類型	Description
connectorLogicalName	string	綁定到頁面的連線參考的邏輯名稱。
dataset	string	要列出表格的資料集。

Returns

一個包含表格資訊陣列的 承諾 。 每個條目具有以下屬性：

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	操作 ID 依據連接器的 Swagger 定義。 將此值傳遞為 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	資料表的內部名稱，取自namelistConnectorTables屬性。 不要使用顯示名稱。

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	資料表的內部名稱，取自namelistConnectorTables屬性。 不要使用顯示名稱。
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	資料表的內部名稱，取自namelistConnectorTables屬性。 不要使用顯示名稱。
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	資料表的內部名稱，取自namelistConnectorTables屬性。 不要使用顯示名稱。
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	資料表的內部名稱，取自namelistConnectorTables屬性。 不要使用顯示名稱。
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 send-message 或 Office 365 使用者）所暴露的命名操作。 表格連接器應該改用查詢與列 CRUD 方法。

Parameters

為這些所需參數設定數值。

Name	類型	Description
connectorLogicalName	string	綁定到頁面的連線參考的邏輯名稱。
operationName	string	操作 ID 依據連接器的 Swagger 定義。
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 定義（例如，使用 listConnectorOperationsgetConnectorSwagger或 ）來驗證操作 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);
}