Metode conectoare pentru pagini generativă

Utilizați metodele de conector ale obiectului dataApi pentru a lucra cu datele expuse de un conector Power Platform legat la pagină.

Notă

Metodele conectoare sunt opționale în contractul partajat dataApi . Unele gazde nu le implementează, deci verificați dacă există o metodă înainte de a o apela. O metodă prezentă nu înseamnă că pagina are un conector legat la acesta sau că conexiunea, setul de date, tabelul sau operațiunea este configurată, autorizată sau permisă conform așteptărilor.

Spre deosebire de metodele de acțiune și de funcții, metodele conectoare resping promisiunea returnată atunci când un apel nu reușește, de exemplu, atunci când referința de conexiune nu poate fi rezolvată, conexiunea nu este autorizată și utilizatorul nu termină solicitarea de consimțământ sau conectorul returnează o stare de eroare. executeConnectorOperation rezolvă cu ok: false pentru majoritatea stărilor de eroare, dar încă respinge pentru o operațiune lipsă, o conexiune neautorizată (403) fără consimțământul finalizat sau o eroare de transport. Încadrare apeluri conector în try/catch.

Metodă Descriere
createConnectorRow Creează un rând nou în tabelul conector specificat.
deleteConnectorRow Șterge un rând din tabelul conector specificat.
executeConnectorOperation Apelează o operațiune denumită expusă de un conector REST (cu cheie de operațiune), cum ar fi Utilizatori Office 365.
getConnectorSwagger Regăsește definiția Swagger (OpenAPI) pentru conector.
getConnectorTableSchema Regăsește schema pentru un tabel (numit și entitate sau listă) expus de conector.
listConnectorDatasets Listează seturile de date disponibile pentru conector.
listConnectorOperations Listează operațiunile expuse de un conector REST (cu cheie de operațiune).
listConnectorTables Listează tabelele disponibile în setul de date de conector specificat.
queryConnectorTable Interoghează un tabel expus de conector cu opțiunile specificate.
retrieveConnectorRow Regăsește un singur rând din tabelul conector specificat.
updateConnectorRow Actualizează un rând existent din tabelul conector specificat.

queryConnectorTable metodă

Interoghează un tabel expus de conector utilizând opțiunile specificate.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină (de exemplu, sp_shared_sharepointonline).
dataset string Setul de date care conține tabelul, cum ar fi un URL de site SharePoint.
tableName string Numele intern al tabelului, din name proprietatea returnată de listConnectorTables. Nu utilizați numele afișat.
options QueryConnectorTableOptions Opțiuni pentru interogarea tabelului.

QueryConnectorTableOptions

Nume Tip Descriere
select string[] (Recomandat) Matrice de nume de coloane de regăsit.
filter string (Opțional) Expresia de filtrare acceptată de conector.
orderBy string (Opțional) Order-by expression supported by the connector.
top number (Opțional) Numărul maxim de rânduri de returnat.

Retururi

O promisiune care conține rezultatul operațiunii. Atunci când operațiunea reușește, promisiunea returnează un obiect care conține un tabel de date cu rezultatele cu aceste proprietăți:

Nume Tip Descriere
rows Object[] Matrice de date de rând.
hasMoreRows boolean Indică dacă sunt disponibile mai multe rânduri.

queryConnectorTable returnează o singură pagină de rezultate. Nu returnează o funcție de continuare și momentan nu există nicio modalitate acceptată de a prelua pagina următoare. Când hasMoreRows este , truemai multe rânduri se potrivesc decât s-au returnat. Restrângeți interogarea cu filtersau spuneți utilizatorului că rezultatele sunt incomplete.

queryConnectorTable example

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

Următoarele exemple presupun că documentsTableName conține tabelul name din listConnectorTables, așa cum se arată mai sus.

listConnectorTables metodă

Listează tabelele (listele sau entitățile) disponibile în setul de date de conector specificat.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
dataset string Setul de date pentru care se listează tabelele.

Retururi

O promisiune care conține o matrice de informații despre tabel. Fiecare intrare are aceste proprietăți:

Nume Tip Descriere
name string Numele intern al tabelului.
displayName string Numele afișat al tabelului.

listConnectorTables example

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

listConnectorDatasets metodă

Listează seturile de date disponibile pentru conector, cum ar fi SharePoint site-urile pe care le poate accesa o conexiune.

Parametri

Setați o valoare pentru acest parametru obligatoriu.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.

Retururi

O promisiune care conține o matrice de informații despre setul de date. Fiecare intrare are aceste proprietăți:

Nume Tip Descriere
name string Numele intern sau identificatorul setului de date.
displayName string Numele afișat al setului de date.

listConnectorDatasets example

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

listConnectorOperations metodă

Listează operațiunile definite în definiția Swagger a conectorului, excluzând operațiunile marcate intern, sortate după numele afișat. Această metodă este foarte utilă pentru conectorii REST (tastă de operațiune), cum ar fi Utilizatori Office 365. Pentru conectori tabelare, utilizați metodele de interogare și de rând în locul operațiunilor pe care le listează această metodă.

Parametri

Setați o valoare pentru acest parametru obligatoriu.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.

Retururi

O promisiune care conține o matrice de informații despre operațiune. Fiecare intrare are aceste proprietăți:

Nume Tip Descriere
name string ID-ul operațiunii, așa cum este definit în definiția Swagger a conectorului. Treceți această valoare la executeConnectorOperation.
displayName string Numele operațiunii ușor de citit de oameni pentru afișare, cum ar fi rezumatul Swagger. Cade înapoi la name dacă nu este definit niciun rezumat.

listConnectorOperations example

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

getConnectorSwagger metodă

Regăsește definiția Swagger (OpenAPI) pentru conector, care descrie operațiunile pe care le expune. Documentul returnat descrie în general conectorul. Nu include scheme coloană tabel pentru conectori tabel. Se utilizează getConnectorTableSchema pentru aceste informații.

Parametri

Setați o valoare pentru acest parametru obligatoriu.

Nume Tip Descriere
connectorApiId string Identificatorul API conector, cum /providers/Microsoft.PowerApps/apis/shared_sharepointonlinear fi . Acest identificator este diferit de numele logic al referinței de conexiune (connectorLogicalName) utilizat de majoritatea celorlalte metode conector.

Retururi

O promisiune care conține definiția Swagger a conectorului ca obiect.

getConnectorSwagger example

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 metodă

Regăsește schema (definițiile coloanelor) pentru un tabel expus de conector. Conectorul definește schema returnată și variază în funcție de conector. Nu presupuneți că include fiecare coloană dinamică pe care o poate conține un tabel.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
dataset string Setul de date care conține tabelul.
tableName string Numele intern al tabelului, din name proprietatea returnată de listConnectorTables. Nu utilizați numele afișat.

Retururi

O promisiune care conține schema tabelului ca obiect.

getConnectorTableSchema example

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 metodă

Regăsește un singur rând din tabelul conector specificat.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
dataset string Setul de date care conține tabelul.
tableName string Numele intern al tabelului, din name proprietatea returnată de listConnectorTables. Nu utilizați numele afișat.
id string ID-ul rândului de regăsit.
options RetrieveConnectorRowOptions (Opțional) Opțiuni pentru regăsirea rândului.

RetrieveConnectorRowOptions

Nume Tip Descriere
select string[] (Recomandat) Matrice de nume de coloane de regăsit. Dacă este omisă, nu este trimisă nicio $select proiectare - conectorul determină ce coloane să returneze și nu garantează returnarea fiecărei coloane din rând.

Retururi

O promisiune care conține datele de rând.

retrieveConnectorRow example

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 metodă

Creează un rând nou în tabelul conector specificat.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
dataset string Setul de date care conține tabelul.
tableName string Numele intern al tabelului, din name proprietatea returnată de listConnectorTables. Nu utilizați numele afișat.
row object Datele de rând de creat.

Retururi

O promisiune care conține corpul răspunsului returnat de conector, dacă există. În funcție de conector, această valoare poate fi rândul creat, un rând parțial sau nicio valoare.

createConnectorRow example

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 metodă

Actualizează un rând existent din tabelul conector specificat.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
dataset string Setul de date care conține tabelul.
tableName string Numele intern al tabelului, din name proprietatea returnată de listConnectorTables. Nu utilizați numele afișat.
id string ID-ul rândului de actualizat.
row object Datele de rând de actualizat.

Retururi

O promisiune care conține corpul răspunsului returnat de conector, dacă există. În funcție de conector, această valoare poate fi rândul actualizat, un rând parțial sau nicio valoare. Pentru a citi valorile curente ale rândului, apelați retrieveConnectorRow.

updateConnectorRow example

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 metodă

Șterge un rând din tabelul conector specificat.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
dataset string Setul de date care conține tabelul.
tableName string Numele intern al tabelului, din name proprietatea returnată de listConnectorTables. Nu utilizați numele afișat.
id string ID-ul rândului de șters.

Retururi

O promisiune care conține rezultatul operațiunii. Atunci când operațiunea reușește, nu returnează nicio valoare.

deleteConnectorRow example

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 metodă

Apelează o operațiune denumită expusă de un conector REST (cu cheie de operațiune), cum ar fi HTTP, Teams send-message sau Utilizatori Office 365. Conectorii tabelare ar trebui să utilizeze în schimb metodele de interogare și de rând CRUD.

Parametri

Setați valorile pentru acești parametri necesari.

Nume Tip Descriere
connectorLogicalName string Numele logic al referinței de conexiune legate la pagină.
operationName string ID-ul operațiunii, așa cum este definit în definiția Swagger a conectorului.
parameters object Parametrii necesari operațiunii. Treceți un obiect gol ({}) dacă operațiunea nu are parametri- acest parametru este necesar chiar și atunci când nu există nimic de trimis.

Retururi

O promisiune care conține rezultatul operațiunii cu aceste proprietăți. Promisiunea respinge dacă referința de conexiune nu poate fi rezolvată, definiția Swagger a conectorului nu poate fi regăsită, operațiunea nu se găsește în aceasta, apelul nu poate fi expediat sau conexiunea nu este autorizată (HTTP 403) și utilizatorul nu termină solicitarea de consimțământ de conexiune.

Nume Tip Descriere
ok boolean true când starea HTTP subiacentă este mai mică de 400. Această stare include stări de redirecționare (3xx), deci nu tratați ok doar ca dovadă că operațiunea a returnat date, verificați status sau inspectați body.
status number Codul de stare HTTP brut returnat de conector.
body unknown Corpul răspunsului JSON analizat sau șirul brut dacă corpul nu este JSON.

executeConnectorOperation example

Următorul exemplu presupune o operațiune numită CopyFile care acceptă sourceUrl și destinationUrl parametri. Verificați ID-ul operațiunii și parametrii săi în raport cu definiția Swagger a conectorului (de exemplu, cu listConnectorOperations sau getConnectorSwagger) înainte de a o utiliza, deoarece operațiunile disponibile și parametrii lor variază în funcție de conector.

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