Metode konektor untuk halaman generatif

Gunakan metode dataApi konektor objek untuk bekerja dengan data yang diekspos oleh konektor Power Platform yang terikat ke halaman.

Note

Metode konektor bersifat opsional dalam kontrak bersama dataApi . Beberapa host tidak mengimplementasikannya, jadi periksa apakah metode ada sebelum memanggilnya. Metode yang ada tidak berarti halaman memiliki konektor yang terikat padanya, atau bahwa koneksi, himpunan data, tabel, atau operasi dikonfigurasi, diotorisasi, atau diizinkan seperti yang diharapkan.

Tidak seperti metode tindakan dan fungsi, metode konektor menolak janji yang dikembalikan ketika panggilan gagal — misalnya, ketika referensi koneksi tidak dapat diselesaikan, koneksi tidak diotorisasi dan pengguna tidak menyelesaikan permintaan persetujuan, atau konektor mengembalikan status kesalahan. executeConnectorOperation ok: false mengatasi sebagian besar status kesalahan, tetapi masih menolak untuk operasi yang hilang, koneksi yang tidak sah (403) tanpa persetujuan yang selesai, atau kegagalan transportasi. Bungkus panggilan konektor di try/catch.

Metode	Description
createConnectorRow	Membuat baris baru dalam tabel konektor yang ditentukan.
deleteConnectorRow	Menghapus baris dari tabel konektor yang ditentukan.
executeConnectorOperation	Memanggil operasi bernama yang diekspos oleh konektor REST (kunci operasi), seperti Pengguna Office 365.
getConnectorSwagger	Mengambil definisi Swagger (OpenAPI) untuk konektor.
getConnectorTableSchema	Mengambil skema untuk tabel (juga disebut entitas atau daftar) yang diekspos oleh konektor.
listConnectorDatasets	Mencantumkan himpunan data yang tersedia untuk konektor.
listConnectorOperations	Mencantumkan operasi yang diekspos oleh konektor REST (bertanda operasi).
listConnectorTables	Mencantumkan tabel yang tersedia dalam himpunan data konektor yang ditentukan.
queryConnectorTable	Mengkueri tabel yang diekspos oleh konektor dengan opsi yang ditentukan.
retrieveConnectorRow	Mengambil satu baris dari tabel konektor yang ditentukan.
updateConnectorRow	Memperbarui baris yang sudah ada dalam tabel konektor yang ditentukan.

metode queryConnectorTable

Mengkueri tabel yang diekspos oleh konektor dengan menggunakan opsi yang ditentukan.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi yang terikat ke halaman (misalnya, sp_shared_sharepointonline).
dataset	string	Himpunan data yang berisi tabel, seperti URL situs SharePoint.
tableName	string	Nama internal tabel, dari properti yang name dikembalikan oleh listConnectorTables. Jangan gunakan nama tampilan.
options	QueryConnectorTableOptions	Opsi untuk mengkueri tabel.

QueryConnectorTableOptions

Name	Type	Description
select	string[]	(Disarankan) Array nama kolom yang akan diambil.
filter	string	(Opsional) Ekspresi filter yang didukung oleh konektor.
orderBy	string	(Opsional) Ekspresi order-by yang didukung oleh konektor.
top	number	(Opsional) Jumlah maksimum baris yang akan dikembalikan.

Returns

Janji yang berisi hasil operasi. Ketika operasi berhasil, janji mengembalikan objek yang berisi tabel data dengan hasil dengan properti ini:

Name	Type	Description
rows	Object[]	Array data baris.
hasMoreRows	boolean	Menunjukkan apakah ada lebih banyak baris yang tersedia.

queryConnectorTable mengembalikan satu halaman hasil. Ini tidak mengembalikan fungsi kelanjutan, dan saat ini tidak ada cara yang didukung untuk mengambil halaman berikutnya. Ketika hasMoreRows adalah , lebih banyak truebaris yang cocok daripada yang dikembalikan. Persempit kueri dengan filter, atau beri tahu pengguna bahwa hasilnya tidak lengkap.

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

Contoh berikut mengasumsikan documentsTableName memegang tabel name dari listConnectorTables, seperti yang ditunjukkan di atas.

metode listConnectorTables

Mencantumkan tabel (daftar atau entitas) yang tersedia dalam himpunan data konektor yang ditentukan.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
dataset	string	Himpunan data untuk mencantumkan tabel.

Returns

Janji yang berisi array informasi tabel. Setiap entri memiliki properti ini:

Name	Type	Description
name	string	Nama internal tabel.
displayName	string	Nama tampilan tabel.

contoh listConnectorTables

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

metode listConnectorDatasets

Mencantumkan himpunan data yang tersedia untuk konektor, seperti situs SharePoint yang dapat diakses koneksi.

Parameters

Tetapkan nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.

Returns

Janji yang berisi array informasi himpunan data. Setiap entri memiliki properti ini:

Name	Type	Description
name	string	Nama internal atau pengidentifikasi himpunan data.
displayName	string	Nama tampilan himpunan data.

contoh listConnectorDatasets

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

metode listConnectorOperations

Mencantumkan operasi yang ditentukan dalam definisi Swagger konektor, tidak termasuk operasi yang ditandai internal, diurutkan menurut nama tampilan. Metode ini paling berguna untuk konektor REST (bertanda operasi) seperti Pengguna Office 365. Untuk konektor tabular, gunakan metode kueri dan baris alih-alih operasi daftar metode ini.

Parameters

Tetapkan nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.

Returns

Janji yang berisi array informasi operasi. Setiap entri memiliki properti ini:

Name	Type	Description
name	string	ID operasi seperti yang didefinisikan dalam definisi Swagger konektor. Teruskan nilai ini ke executeConnectorOperation.
displayName	string	Nama operasi yang dapat dibaca manusia untuk ditampilkan, seperti ringkasan Swagger. Kembali ke name jika tidak ada ringkasan yang ditentukan.

contoh listConnectorOperations

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

metode getConnectorSwagger

Mengambil definisi Swagger (OpenAPI) untuk konektor, yang menjelaskan operasi yang dieksposnya. Dokumen yang dikembalikan menjelaskan konektor secara keseluruhan. Ini tidak termasuk skema kolom per tabel untuk konektor tabular. Gunakan getConnectorTableSchema untuk informasi tersebut.

Parameters

Tetapkan nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorApiId	string	Pengidentifikasi API konektor, seperti /providers/Microsoft.PowerApps/apis/shared_sharepointonline. Pengidentifikasi ini berbeda dari nama logis referensi koneksi (connectorLogicalName) yang digunakan oleh sebagian besar metode konektor lainnya.

Returns

Janji yang berisi definisi Swagger konektor 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"
);

metode getConnectorTableSchema

Mengambil skema (definisi kolom) untuk tabel yang diekspos oleh konektor. Konektor menentukan skema yang dikembalikannya, dan bervariasi menurut konektor. Jangan berasumsi bahwa tabel menyertakan setiap kolom dinamis yang mungkin berisi tabel.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
dataset	string	Himpunan data yang berisi tabel.
tableName	string	Nama internal tabel, dari properti yang name dikembalikan oleh listConnectorTables. Jangan gunakan nama tampilan.

Returns

Janji yang berisi skema tabel 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
);

metode retrieveConnectorRow

Mengambil satu baris dari tabel konektor yang ditentukan.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
dataset	string	Himpunan data yang berisi tabel.
tableName	string	Nama internal tabel, dari properti yang name dikembalikan oleh listConnectorTables. Jangan gunakan nama tampilan.
id	string	ID baris yang akan diambil.
options	RetrieveConnectorRowOptions	(Opsional) Opsi untuk mengambil baris.

RetrieveConnectorRowOptions

Name	Type	Description
select	string[]	(Disarankan) Array nama kolom yang akan diambil. Jika dihilangkan, tidak ada $select proyeksi yang dikirim — konektor menentukan kolom mana yang akan dikembalikan dan tidak menjamin untuk mengembalikan setiap kolom dalam baris.

Returns

Janji yang berisi 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"
);

metode createConnectorRow

Membuat baris baru dalam tabel konektor yang ditentukan.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
dataset	string	Himpunan data yang berisi tabel.
tableName	string	Nama internal tabel, dari properti yang name dikembalikan oleh listConnectorTables. Jangan gunakan nama tampilan.
row	object	Data baris yang akan dibuat.

Returns

Janji yang berisi isi respons yang dikembalikan oleh konektor, jika ada. Bergantung pada konektor, nilai ini bisa menjadi baris yang dibuat, baris parsial, atau tanpa 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" }
);

metode updateConnectorRow

Memperbarui baris yang sudah ada dalam tabel konektor yang ditentukan.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
dataset	string	Himpunan data yang berisi tabel.
tableName	string	Nama internal tabel, dari properti yang name dikembalikan oleh listConnectorTables. Jangan gunakan nama tampilan.
id	string	ID baris yang akan diperbarui.
row	object	Data baris yang akan diperbarui.

Returns

Janji yang berisi isi respons yang dikembalikan oleh konektor, jika ada. Bergantung pada konektor, nilai ini bisa menjadi baris yang diperbarui, baris parsial, atau tanpa nilai. Untuk membaca nilai baris saat ini, 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" }
);

metode deleteConnectorRow

Menghapus baris dari tabel konektor yang ditentukan.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
dataset	string	Himpunan data yang berisi tabel.
tableName	string	Nama internal tabel, dari properti yang name dikembalikan oleh listConnectorTables. Jangan gunakan nama tampilan.
id	string	ID baris yang akan dihapus.

Returns

Janji yang berisi hasil operasi. Ketika operasi berhasil, operasi 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"
);

metode executeConnectorOperation

Memanggil operasi bernama yang diekspos oleh konektor REST (kunci operasi), seperti HTTP, pesan kirim Teams, atau Pengguna Office 365. Konektor tabular harus menggunakan metode CRUD kueri dan baris sebagai gantinya.

Parameters

Atur nilai untuk parameter yang diperlukan ini.

Name	Type	Description
connectorLogicalName	string	Nama logis referensi koneksi terikat ke halaman.
operationName	string	ID operasi seperti yang didefinisikan dalam definisi Swagger konektor.
parameters	object	Parameter yang diperlukan oleh operasi. Teruskan objek kosong ({}) jika operasi tidak mengambil parameter — parameter ini diperlukan bahkan ketika tidak ada yang perlu dikirim.

Returns

Janji yang berisi hasil operasi dengan properti ini. Janji menolak jika referensi koneksi tidak dapat diselesaikan, definisi Swagger konektor tidak dapat diambil, operasi tidak ditemukan di dalamnya, panggilan tidak dapat dikirim, atau koneksi tidak diotorisasi (HTTP 403) dan pengguna tidak menyelesaikan permintaan persetujuan koneksi.

Name	Type	Description
ok	boolean	true ketika status HTTP yang mendasar kurang dari 400. Status ini mencakup status pengalihan (3xx), jadi jangan memperlakukan ok sendiri sebagai bukti operasi mengembalikan data — juga periksa status atau periksa body.
status	number	Kode status HTTP mentah yang dikembalikan oleh konektor.
body	unknown	Isi respons JSON yang diurai, atau string mentah jika isinya bukan JSON.

contoh executeConnectorOperation

Contoh berikut mengasumsikan operasi bernama CopyFile yang menerima sourceUrl dan destinationUrl parameter. Verifikasi ID operasi dan parameternya terhadap definisi Swagger konektor sendiri (misalnya, dengan listConnectorOperations atau getConnectorSwagger) sebelum menggunakannya, karena operasi yang tersedia dan parameternya bervariasi menurut konektor.

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