Kaedah penyambung untuk halaman generatif

Gunakan kaedah dataApi penyambung objek untuk bekerja dengan data yang didedahkan oleh penyambung Power Platform yang terikat pada halaman.

Nota

Kaedah penyambung adalah pilihan dalam kontrak bersama dataApi . Sesetengah hos tidak melaksanakannya, jadi periksa sama ada sesuatu kaedah wujud sebelum memanggilnya. Kehadiran kaedah tidak bermakna halaman mempunyai penyambung yang terikat kepadanya, atau sambungan, set data, jadual, atau operasi dikonfigurasi, dibenarkan, atau dibenarkan seperti yang dijangka.

Tidak seperti kaedah tindakan dan fungsi, kaedah penyambung menolak janji yang dikembalikan apabila panggilan gagal — contohnya, apabila rujukan sambungan tidak dapat diselesaikan, sambungan tidak dibenarkan dan pengguna tidak melengkapkan prompt persetujuan, atau penyambung mengembalikan status ralat. executeConnectorOperation menyelesaikan dengan ok: false untuk kebanyakan status ralat, tetapi masih menolak untuk operasi yang hilang, sambungan tanpa kebenaran (403) tanpa kebenaran lengkap, atau kegagalan pengangkutan. Penyambung wrap memanggil masuk try/catch.

Kaedah	Perihalan
createConnectorRow	Mencipta baris baru dalam jadual penyambung yang ditentukan.
deleteConnectorRow	Memadam baris daripada jadual penyambung yang ditentukan.
executeConnectorOperation	Memanggil operasi bernama yang didedahkan oleh penyambung REST (operation-keyed), seperti Office 365 Users.
getConnectorSwagger	Mengambil definisi Swagger (OpenAPI) untuk penyambung.
getConnectorTableSchema	Mengambil skema untuk jadual (juga dipanggil entiti atau senarai) yang didedahkan oleh penyambung.
listConnectorDatasets	Menyenaraikan set data yang tersedia untuk penyambung.
listConnectorOperations	Menyenaraikan operasi yang didedahkan oleh penyambung REST (berkunci operasi).
listConnectorTables	Menyenaraikan jadual yang tersedia dalam set data penyambung yang ditentukan.
queryConnectorTable	Membuat pertanyaan kepada jadual yang didedahkan oleh penyambung dengan pilihan yang ditetapkan.
retrieveConnectorRow	Mengambil satu baris daripada jadual penyambung yang ditentukan.
updateConnectorRow	Mengemas kini baris sedia ada dalam jadual penyambung yang ditentukan.

queryConnectorTable Kaedah

Membuat pertanyaan pada jadual yang didedahkan oleh penyambung menggunakan pilihan yang ditetapkan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman (contohnya, sp_shared_sharepointonline).
dataset	string	Set data yang mengandungi jadual, seperti URL laman SharePoint.
tableName	string	Nama dalaman jadual, daripada name sifat yang dikembalikan oleh listConnectorTables. Jangan gunakan nama paparan.
options	QueryConnectorTableOptions	Pilihan untuk membuat pertanyaan pada jadual.

QueryConnectorTableOptions

Nama	Jenis	Perihalan
select	string[]	(Disyorkan) Tatasusunan nama lajur untuk mendapatkan semula.
filter	string	(Pilihan) Ungkapan penapis disokong oleh penyambung.
orderBy	string	(Pilihan) Ungkapan urutan-mengikut yang disokong oleh penyambung.
top	number	(Pilihan) Bilangan baris maksimum untuk dikembalikan.

Pulangan

Janji yang mengandungi hasil operasi. Apabila operasi berjaya, janji mengembalikan objek yang mengandungi jadual data dengan hasil dengan sifat ini:

Nama	Jenis	Perihalan
rows	Object[]	Tatasusunan data baris.
hasMoreRows	boolean	Menunjukkan jika terdapat lebih banyak baris yang tersedia.

queryConnectorTable Mengembalikan satu halaman keputusan. Ia tidak mengembalikan fungsi kesinambungan, dan tiada cara yang disokong untuk mengambil halaman seterusnya buat masa ini. Apabila hasMoreRows ialah true, lebih banyak baris dipadankan daripada yang dikembalikan. Sempitkan pertanyaan dengan filter, atau beritahu pengguna bahawa hasilnya tidak lengkap.

contoh jadual queryConnector

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

Contoh berikut mengandaikan documentsTableName jadual name dari listConnectorTables, seperti yang ditunjukkan di atas.

listConnectorTables Kaedah

Menyenaraikan jadual (senarai atau entiti) yang tersedia dalam set data penyambung yang ditentukan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
dataset	string	Set data untuk menyenaraikan jadual.

Pulangan

Janji yang mengandungi tatasusunan maklumat jadual. Setiap entri mempunyai sifat-sifat berikut:

Nama	Jenis	Perihalan
name	string	Nama dalaman jadual.
displayName	string	Nama paparan jadual.

contoh listConnectorTables

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

listConnectorDatasets Kaedah

Menyenaraikan set data yang tersedia untuk penyambung, seperti tapak SharePoint yang boleh diakses oleh sambungan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.

Pulangan

Janji yang mengandungi tatasusunan maklumat set data. Setiap entri mempunyai sifat-sifat berikut:

Nama	Jenis	Perihalan
name	string	Nama dalaman atau pengecam set data.
displayName	string	Nama paparan set data.

contoh set data listConnectorDatasets

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

listConnectorOperations Kaedah

Menyenaraikan operasi yang ditakrifkan dalam definisi Swagger penyambung, kecuali operasi yang ditandakan dalaman, disusun mengikut nama paparan. Kaedah ini paling berguna untuk penyambung REST (operation-keyed) seperti Office 365 Users. Untuk penyambung tabular, gunakan kaedah pertanyaan dan baris sebagai ganti operasi yang disenaraikan oleh kaedah ini.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.

Pulangan

Janji yang mengandungi tatasusunan maklumat operasi. Setiap entri mempunyai sifat-sifat berikut:

Nama	Jenis	Perihalan
name	string	ID operasi seperti yang ditakrifkan dalam definisi Swagger penyambung. Serahkan nilai ini kepada executeConnectorOperation.
displayName	string	Nama operasi yang boleh dibaca manusia untuk paparan, seperti ringkasan Swagger. Bergantung kepada name jika tiada ringkasan yang ditakrifkan.

contoh listConnectorOperations

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

getConnectorSwagger Kaedah

Mengambil definisi Swagger (OpenAPI) untuk penyambung, yang menerangkan operasi yang didedahkan. Dokumen yang dikembalikan menerangkan keseluruhan penyambung tersebut. Ia tidak termasuk skema lajur setiap jadual untuk penyambung jadual. Gunakan getConnectorTableSchema untuk maklumat itu.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorApiId	string	Pengenal API penyambung, seperti /providers/Microsoft.PowerApps/apis/shared_sharepointonline. Pengenal ini berbeza daripada nama logik rujukan sambungan (connectorLogicalName) yang digunakan oleh kebanyakan kaedah penyambung lain.

Pulangan

Janji yang mengandungi definisi Swagger penyambung sebagai objek.

Contoh 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 Kaedah

Mengambil skema (definisi lajur) untuk jadual yang didedahkan oleh penyaung. Penyambung menentukan skema yang dikembalikan, dan ia berbeza mengikut penyambung. Jangan anggap ia merangkumi setiap lajur dinamik yang mungkin terkandung dalam jadual.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
dataset	string	Set data yang mengandungi jadual.
tableName	string	Nama dalaman jadual, daripada name sifat yang dikembalikan oleh listConnectorTables. Jangan gunakan nama paparan.

Pulangan

Janji yang mengandungi skema jadual sebagai objek.

Contoh 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 Kaedah

Mengambil satu baris daripada jadual penyambung yang ditentukan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
dataset	string	Set data yang mengandungi jadual.
tableName	string	Nama dalaman jadual, daripada name sifat yang dikembalikan oleh listConnectorTables. Jangan gunakan nama paparan.
id	string	ID baris yang hendak diambil.
options	RetrieveConnectorRowOptions	(Pilihan) Pilihan untuk mendapatkan baris.

RetrieveConnectorRowOptions

Nama	Jenis	Perihalan
select	string[]	(Disyorkan) Tatasusunan nama lajur untuk mendapatkan semula. Jika diabaikan, tiada $select unjuran dihantar — penyambung menentukan lajur mana yang akan dikembalikan dan tidak menjamin untuk mengembalikan setiap lajur dalam baris.

Pulangan

Janji yang mengandungi data baris.

Contoh 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 Kaedah

Mencipta baris baru dalam jadual penyambung yang ditentukan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
dataset	string	Set data yang mengandungi jadual.
tableName	string	Nama dalaman jadual, daripada name sifat yang dikembalikan oleh listConnectorTables. Jangan gunakan nama paparan.
row	object	Data baris untuk dibuat.

Pulangan

Janji yang mengandungi badan respons yang dikembalikan oleh penyambung, jika ada. Bergantung pada penyambung, nilai ini boleh menjadi baris yang dicipta, baris separa, atau tiada nilai.

contoh 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 Kaedah

Mengemas kini baris sedia ada dalam jadual penyambung yang ditentukan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
dataset	string	Set data yang mengandungi jadual.
tableName	string	Nama dalaman jadual, daripada name sifat yang dikembalikan oleh listConnectorTables. Jangan gunakan nama paparan.
id	string	ID baris untuk dikemas kini.
row	object	Data baris untuk dikemas kini.

Pulangan

Janji yang mengandungi badan respons yang dikembalikan oleh penyambung, jika ada. Bergantung pada penyambung, nilai ini boleh menjadi baris yang dikemas kini, baris separa, atau tiada nilai. Untuk membaca nilai semasa baris, panggil retrieveConnectorRow.

contoh 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 Kaedah

Memadam baris daripada jadual penyambung yang ditentukan.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
dataset	string	Set data yang mengandungi jadual.
tableName	string	Nama dalaman jadual, daripada name sifat yang dikembalikan oleh listConnectorTables. Jangan gunakan nama paparan.
id	string	ID baris untuk dipadamkan.

Pulangan

Janji yang mengandungi hasil operasi. Apabila operasi berjaya, ia tidak mengembalikan nilai.

contoh 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 Kaedah

Memanggil operasi bernama yang didedahkan oleh penyambung REST (operation-keyed), seperti HTTP, Teams send-message, atau Office 365 Users. Penyambung tabular harus menggunakan kaedah CRUD pertanyaan dan baris sebagai gantinya.

Parameter

Tetapkan nilai untuk parameter yang diperlukan ini.

Nama	Jenis	Perihalan
connectorLogicalName	string	Nama logik rujukan sambungan yang terikat pada halaman.
operationName	string	ID operasi seperti yang ditakrifkan dalam definisi Swagger penyambung.
parameters	object	Parameter yang diperlukan oleh operasi. Pass objek kosong ({}) jika operasi tidak mengambil sebarang parameter — parameter ini diperlukan walaupun tiada apa yang perlu dihantar.

Pulangan

Janji yang mengandungi hasil operasi dengan sifat-sifat ini. Janji ditolak jika rujukan sambungan tidak dapat diselesaikan, definisi Swagger penyambung tidak dapat diperoleh, operasi tidak ditemui di dalamnya, panggilan tidak dapat dihantar, atau sambungan tidak dibenarkan (HTTP 403) dan pengguna tidak melengkapkan prompt persetujuan sambungan.

Nama	Jenis	Perihalan
ok	boolean	true apabila status HTTP asas kurang daripada 400. Status ini termasuk status pengalihan (3xx), jadi jangan anggap ok hanya sebagai bukti operasi yang mengembalikan data — juga periksa status atau periksa body.
status	number	Kod status HTTP mentah yang dikembalikan oleh penyambung.
body	unknown	Badan tindak balas JSON yang dipanrai, atau rentetan mentah jika badan bukan JSON.

Contoh executeConnectorOperation

Contoh berikut mengandaikan operasi bernama CopyFile yang menerima sourceUrl dan destinationUrl parameter. Sahkan ID operasi dan parameternya dengan definisi Swagger penyambung sendiri (contohnya, dengan listConnectorOperations atau getConnectorSwagger) sebelum menggunakannya, kerana operasi yang tersedia dan parameternya berbeza mengikut penyambung.

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