生成ページのコネクタ メソッド

ページにバインドされた Power Platform コネクタによって公開されるデータを操作するには、 dataApi オブジェクトのコネクタ メソッドを使用します。

Note

コネクタ メソッドは、共有 dataApi コントラクトでは省略可能です。 一部のホストでは実装されないため、メソッドを呼び出す前にメソッドが存在することを確認してください。 存在するメソッドは、ページにコネクタがバインドされていること、または接続、データセット、テーブル、または操作が期待どおりに構成、承認、または許可されていることを意味するものではありません。

アクションメソッドや関数メソッドとは異なり、コネクタ メソッドは、呼び出しが失敗したときに返された Promise を拒否します。たとえば、接続参照を解決できない場合、接続が承認されておらず、ユーザーが同意プロンプトを完了しない場合や、コネクタがエラー状態を返す場合などです。 executeConnectorOperation は、ほとんどのエラー状態の ok: false で解決されますが、不足している操作、未承認の接続 (403) が完了していない場合、またはトランスポートエラーが発生しても拒否されます。 コネクタの呼び出しを try/catchでラップします。

メソッド	Description
createConnectorRow	指定したコネクタ テーブルに新しい行を作成します。
deleteConnectorRow	指定したコネクタ テーブルから行を削除します。
executeConnectorOperation	REST (操作キー付き) コネクタによって公開される名前付き操作 (Office 365 ユーザーなど) を呼び出します。
getConnectorSwagger	コネクタの Swagger (OpenAPI) 定義を取得します。
getConnectorTableSchema	コネクタによって公開されるテーブル (エンティティまたはリストとも呼ばれます) のスキーマを取得します。
listConnectorDatasets	コネクタで使用できるデータセットを一覧表示します。
listConnectorOperations	REST (操作キー付き) コネクタによって公開される操作を一覧表示します。
listConnectorTables	指定したコネクタ データセットで使用できるテーブルを一覧表示します。
queryConnectorTable	指定したオプションを使用して、コネクタによって公開されるテーブルに対してクエリを実行します。
retrieveConnectorRow	指定したコネクタ テーブルから 1 行を取得します。
updateConnectorRow	指定したコネクタ テーブル内の既存の行を更新します。

queryConnectorTable メソッド

指定したオプションを使用して、コネクタによって公開されるテーブルに対してクエリを実行します。

Parameters

これらの必須パラメーターの値を設定します。

Name	タイプ	Description
connectorLogicalName	string	ページにバインドされている接続参照の論理名 (たとえば、 sp_shared_sharepointonline)。
dataset	string	SharePoint サイト URL など、テーブルを含むデータセット。
tableName	string	listConnectorTablesによって返されるname プロパティのテーブルの内部名。 表示名は使用しないでください。
options	QueryConnectorTableOptions	テーブルに対してクエリを実行するためのオプション。

QueryConnectorTableOptions

Name	タイプ	Description
select	string[]	(推奨)取得する列名の配列。
filter	string	(省略可能)コネクタでサポートされているフィルター式。
orderBy	string	(省略可能)コネクタでサポートされている Order-by 式。
top	number	(省略可能)返される行の最大数。

Returns

操作の結果を含む Promise 。 操作が成功すると、promise は次のプロパティを持つ結果を含むデータ テーブルを含むオブジェクトを返します。

Name	タイプ	Description
rows	Object[]	行データの配列。
hasMoreRows	boolean	使用可能な行が増えるかどうかを示します。

queryConnectorTable は、結果の 1 ページを返します。 継続関数は返されません。現在、次のページをフェッチする方法はサポートされていません。 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

テーブル情報の配列を含む 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

データセット情報の配列を含む Promise 。 各エントリには、次のプロパティがあります。

Name	タイプ	Description
name	string	データセットの内部名または識別子。
displayName	string	データセットの表示名。

listConnectorDatasets の例

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

listConnectorOperations メソッド

コネクタの Swagger 定義で定義されている操作を一覧表示します。内部としてマークされた操作は表示名で並べ替えされません。 この方法は、Office 365 ユーザーなどの REST (操作キー付き) コネクタに最も役立ちます。 表形式コネクタの場合は、このメソッドが一覧表示する操作ではなく、クエリメソッドと行メソッドを使用します。

Parameters

この必須パラメーターの値を設定します。

Name	タイプ	Description
connectorLogicalName	string	ページにバインドされている接続参照の論理名。

Returns

操作情報の配列を含む Promise 。 各エントリには、次のプロパティがあります。

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 定義をオブジェクトとして含む Promise 。

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	listConnectorTablesによって返されるname プロパティのテーブルの内部名。 表示名は使用しないでください。

Returns

テーブルのスキーマをオブジェクトとして含む Promise 。

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 メソッド

指定したコネクタ テーブルから 1 行を取得します。

Parameters

これらの必須パラメーターの値を設定します。

Name	タイプ	Description
connectorLogicalName	string	ページにバインドされている接続参照の論理名。
dataset	string	テーブルを含むデータセット。
tableName	string	listConnectorTablesによって返されるname プロパティのテーブルの内部名。 表示名は使用しないでください。
id	string	取得する行の ID。
options	RetrieveConnectorRowOptions	(省略可能)行を取得するためのオプション。

RetrieveConnectorRowOptions

Name	タイプ	Description
select	string[]	(推奨)取得する列名の配列。 省略した場合、 $select プロジェクションは送信されません。コネクタは返す列を決定し、行のすべての列を返すとは限りません。

Returns

行データを含む Promise 。

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	listConnectorTablesによって返されるname プロパティのテーブルの内部名。 表示名は使用しないでください。
row	object	作成する行データ。

Returns

コネクタによって返される応答本文 (存在する場合) を含む Promise 。 コネクタに応じて、この値は、作成された行、部分的な行、または値を指定できません。

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	listConnectorTablesによって返されるname プロパティのテーブルの内部名。 表示名は使用しないでください。
id	string	更新する行の ID。
row	object	更新する行データ。

Returns

コネクタによって返される応答本文 (存在する場合) を含む Promise 。 コネクタに応じて、この値は更新された行、部分的な行、または値を指定できません。 行の現在の値を読み取るために、 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	listConnectorTablesによって返されるname プロパティのテーブルの内部名。 表示名は使用しないでください。
id	string	削除する行の ID。

Returns

操作の結果を含む Promise 。 操作が成功すると、値は返されません。

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

これらのプロパティを含む操作結果を含む Promise 。 接続参照を解決できない、コネクタの Swagger 定義を取得できない、操作が見つからない、呼び出しをディスパッチできない、接続が承認されていない (HTTP 403) 場合、ユーザーが接続の同意プロンプトを完了しない場合、promise は拒否します。

Name	タイプ	Description
ok	boolean	true 基になる HTTP 状態が 400 未満の場合。 この状態にはリダイレクト (3xx) 状態が含まれるため、 ok だけを操作から返されたデータの証拠として扱わないようにします。また、 status を確認したり、 bodyを検査したりしないでください。
status	number	コネクタによって返される生の HTTP 状態コード。
body	unknown	解析された JSON 応答本文。本文が JSON でない場合は生の文字列。

executeConnectorOperation の例

次の例では、sourceUrlパラメーターとdestinationUrl パラメーターを受け取る CopyFile という名前の操作を想定しています。 使用できる操作とそのパラメーターはコネクタによって異なるため、操作 ID とそのパラメーターを使用する前に、コネクタ独自の Swagger 定義 ( listConnectorOperations や getConnectorSwaggerなど) に対して確認します。

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);
}