Metodi del connettore per le pagine generative

Usare i metodi connettore dell'oggetto dataApi per lavorare con i dati esposti da un connettore Power Platform associato alla pagina.

Annotazioni

I metodi del connettore sono facoltativi nel contratto condiviso dataApi . Alcuni host non li implementano, quindi verificare che esista un metodo prima di chiamarlo. Un metodo presente non significa che alla pagina sia associato un connettore o che la connessione, il set di dati, la tabella o l'operazione sia configurato, autorizzato o consentito come previsto.

A differenza dei metodi di azione e funzione, i metodi del connettore rifiutano la promessa restituita quando una chiamata ha esito negativo, ad esempio quando il riferimento alla connessione non può essere risolto, la connessione non è autorizzata e l'utente non completa la richiesta di consenso o il connettore restituisce uno stato di errore. executeConnectorOperation viene risolto con ok: false per la maggior parte degli stati di errore, ma rifiuta comunque per un'operazione mancante, una connessione non autorizzata (403) senza consenso completato o un errore di trasporto. Eseguire il wrapping delle chiamate al connettore in try/catch.

Metodo	Description
createConnectorRow	Crea una nuova riga nella tabella del connettore specificata.
deleteConnectorRow	Elimina una riga dalla tabella del connettore specificata.
executeConnectorOperation	Richiama un'operazione denominata esposta da un connettore REST (con chiave operativa), ad esempio Utenti di Office 365.
getConnectorSwagger	Recupera la definizione di Swagger (OpenAPI) per il connettore.
getConnectorTableSchema	Recupera lo schema per una tabella (detta anche entità o elenco) esposta dal connettore.
listConnectorDatasets	Elenca i set di dati disponibili per il connettore.
listConnectorOperations	Elenca le operazioni esposte da un connettore REST (con chiave operativa).
listConnectorTables	Elenca le tabelle disponibili nel set di dati del connettore specificato.
queryConnectorTable	Esegue una query su una tabella esposta dal connettore con le opzioni specificate.
retrieveConnectorRow	Recupera una singola riga dalla tabella del connettore specificata.
updateConnectorRow	Aggiorna una riga esistente nella tabella del connettore specificata.

Metodo queryConnectorTable

Esegue una query su una tabella esposta dal connettore usando le opzioni specificate.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina , ad esempio sp_shared_sharepointonline.
dataset	string	Set di dati contenente la tabella, ad esempio un URL del sito SharePoint.
tableName	string	Nome interno della tabella, dalla name proprietà restituita da listConnectorTables. Non usare il nome visualizzato.
options	QueryConnectorTableOptions	Opzioni per l'esecuzione di query sulla tabella.

QueryConnectorTableOptions

Name	Type	Description
select	string[]	(Scelta consigliata) Matrice di nomi di colonna da recuperare.
filter	string	(Facoltativo) Espressione di filtro supportata dal connettore.
orderBy	string	(Facoltativo) Espressione order-by supportata dal connettore.
top	number	(Facoltativo) Numero massimo di righe da restituire.

Returns

Promessa contenente il risultato dell'operazione. Quando l'operazione ha esito positivo, la promessa restituisce un oggetto contenente una tabella dati con i risultati con queste proprietà:

Name	Type	Description
rows	Object[]	Matrice di dati di riga.
hasMoreRows	boolean	Indica se sono disponibili più righe.

queryConnectorTable restituisce una singola pagina di risultati. Non restituisce una funzione di continuazione e attualmente non è possibile recuperare la pagina successiva. Quando hasMoreRows è true, più righe corrispondono rispetto a quelle restituite. Restringere la query con filtero indicare all'utente che i risultati sono incompleti.

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

Gli esempi seguenti presuppongono che documentsTableName contenga la tabella da namelistConnectorTables, come illustrato in precedenza.

Metodo listConnectorTables

Elenca le tabelle (elenchi o entità) disponibili nel set di dati del connettore specificato.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
dataset	string	Set di dati per cui elencare le tabelle.

Returns

Promessa contenente una matrice di informazioni sulla tabella. Ogni voce ha queste proprietà:

Name	Type	Description
name	string	Nome interno della tabella.
displayName	string	Nome visualizzato della tabella.

Esempio listConnectorTables

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

Metodo listConnectorDatasets

Elenca i set di dati disponibili per il connettore, ad esempio i siti SharePoint a cui può accedere una connessione.

Parameters

Impostare un valore per questo parametro obbligatorio.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.

Returns

Promessa contenente una matrice di informazioni sul set di dati. Ogni voce ha queste proprietà:

Name	Type	Description
name	string	Nome interno o identificatore del set di dati.
displayName	string	Nome visualizzato del set di dati.

Esempio listConnectorDatasets

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

Metodo listConnectorOperations

Elenca le operazioni definite nella definizione Swagger del connettore, escluse le operazioni contrassegnate come interne, ordinate in base al nome visualizzato. Questo metodo è più utile per i connettori REST (operation-keyed), ad esempio Utenti di Office 365. Per i connettori tabulari, usare i metodi di query e di riga anziché le operazioni elencate da questo metodo.

Parameters

Impostare un valore per questo parametro obbligatorio.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.

Returns

Promessa contenente una matrice di informazioni sull'operazione. Ogni voce ha queste proprietà:

Name	Type	Description
name	string	ID operazione come definito nella definizione Swagger del connettore. Passare questo valore a executeConnectorOperation.
displayName	string	Nome dell'operazione leggibile per la visualizzazione, ad esempio il riepilogo di Swagger. Esegue il fallback a name se non è definito alcun riepilogo.

Esempio listConnectorOperations

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

Metodo getConnectorSwagger

Recupera la definizione di Swagger (OpenAPI) per il connettore, che descrive le operazioni esposte. Il documento restituito descrive complessivamente il connettore. Non include schemi di colonna per tabella per i connettori tabulari. Usare getConnectorTableSchema per tali informazioni.

Parameters

Impostare un valore per questo parametro obbligatorio.

Name	Type	Description
connectorApiId	string	Identificatore dell'API del connettore, ad esempio /providers/Microsoft.PowerApps/apis/shared_sharepointonline. Questo identificatore è diverso dal nome logico di riferimento alla connessione (connectorLogicalName) usato dalla maggior parte degli altri metodi del connettore.

Returns

Promessa contenente la definizione Swagger del connettore come oggetto .

Esempio di 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"
);

Metodo getConnectorTableSchema

Recupera lo schema (definizioni di colonna) per una tabella esposta dal connettore. Il connettore definisce lo schema restituito e varia in base al connettore. Non presupporre che includa tutte le colonne dinamiche che una tabella può contenere.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
dataset	string	Set di dati contenente la tabella.
tableName	string	Nome interno della tabella, dalla name proprietà restituita da listConnectorTables. Non usare il nome visualizzato.

Returns

Promessa contenente lo schema della tabella come oggetto .

Esempio di 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
);

Metodo retrieveConnectorRow

Recupera una singola riga dalla tabella del connettore specificata.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
dataset	string	Set di dati contenente la tabella.
tableName	string	Nome interno della tabella, dalla name proprietà restituita da listConnectorTables. Non usare il nome visualizzato.
id	string	ID della riga da recuperare.
options	RetrieveConnectorRowOptions	(Facoltativo) Opzioni per il recupero della riga.

RetrieveConnectorRowOptions

Name	Type	Description
select	string[]	(Scelta consigliata) Matrice di nomi di colonna da recuperare. Se omesso, non viene inviata alcuna $select proiezione. Il connettore determina le colonne da restituire e non garantisce la restituzione di ogni colonna nella riga.

Returns

Promessa contenente i dati della riga.

Esempio di 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"
);

Metodo createConnectorRow

Crea una nuova riga nella tabella del connettore specificata.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
dataset	string	Set di dati contenente la tabella.
tableName	string	Nome interno della tabella, dalla name proprietà restituita da listConnectorTables. Non usare il nome visualizzato.
row	object	Dati di riga da creare.

Returns

Promessa contenente il corpo della risposta restituito dal connettore, se presente. A seconda del connettore, questo valore può essere la riga creata, una riga parziale o nessun valore.

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

Metodo updateConnectorRow

Aggiorna una riga esistente nella tabella del connettore specificata.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
dataset	string	Set di dati contenente la tabella.
tableName	string	Nome interno della tabella, dalla name proprietà restituita da listConnectorTables. Non usare il nome visualizzato.
id	string	ID della riga da aggiornare.
row	object	Dati di riga da aggiornare.

Returns

Promessa contenente il corpo della risposta restituito dal connettore, se presente. A seconda del connettore, questo valore può essere la riga aggiornata, una riga parziale o nessun valore. Per leggere i valori correnti della riga, chiamare retrieveConnectorRow.

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

Metodo deleteConnectorRow

Elimina una riga dalla tabella del connettore specificata.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
dataset	string	Set di dati contenente la tabella.
tableName	string	Nome interno della tabella, dalla name proprietà restituita da listConnectorTables. Non usare il nome visualizzato.
id	string	ID della riga da eliminare.

Returns

Promessa contenente il risultato dell'operazione. Quando l'operazione ha esito positivo, non restituisce alcun valore.

Esempio di 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"
);

Metodo executeConnectorOperation

Richiama un'operazione denominata esposta da un connettore REST (con chiave operativa), ad esempio HTTP, Teams send-message o Utenti di Office 365. I connettori tabulari devono usare invece i metodi CRUD di query e riga.

Parameters

Impostare i valori per questi parametri obbligatori.

Name	Type	Description
connectorLogicalName	string	Nome logico del riferimento di connessione associato alla pagina.
operationName	string	ID operazione come definito nella definizione Swagger del connettore.
parameters	object	Parametri richiesti dall'operazione. Passare un oggetto vuoto ({}) se l'operazione non accetta parametri. Questo parametro è obbligatorio anche quando non è necessario inviare alcun elemento.

Returns

Promessa contenente il risultato dell'operazione con queste proprietà. La promessa rifiuta se il riferimento alla connessione non può essere risolto, la definizione Swagger del connettore non può essere recuperata, l'operazione non viene trovata, la chiamata non può essere inviata o la connessione non è autorizzata (HTTP 403) e l'utente non completa la richiesta di consenso della connessione.

Name	Type	Description
ok	boolean	true quando lo stato HTTP sottostante è minore di 400. Questo stato include gli stati di reindirizzamento (3xx), quindi non considerare ok da solo come prova i dati restituiti dall'operazione, anche controllare status o controllare body.
status	number	Codice di stato HTTP non elaborato restituito dal connettore.
body	unknown	Corpo della risposta JSON analizzato o stringa non elaborata se il corpo non è JSON.

Esempio executeConnectorOperation

Nell'esempio seguente si presuppone un'operazione denominata CopyFile che accetta sourceUrl parametri e destinationUrl . Verificare l'ID operazione e i relativi parametri rispetto alla definizione Swagger del connettore (ad esempio, con listConnectorOperations o getConnectorSwagger) prima di usarlo, poiché le operazioni disponibili e i relativi parametri variano in base al connettore.

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