Mètodes connectors per a pàgines generatives

Utilitza els mètodes de connector de l'objecte dataApi per treballar amb dades exposades per un connector de Power Platform vinculat a la pàgina.

Nota

Els mètodes de connector són opcionals en el contracte compartit dataApi . Alguns hosts no els implementen, així que comprova que existeix un mètode abans de cridar-lo. Que el mètode estigui present no vol dir que la pàgina tingui un connector vinculat, ni que la connexió, conjunt de dades, taula o operació estigui configurada, autoritzada o permesa com s'esperava.

A diferència dels mètodes d'acció i funció, els mètodes connectors rebutgen la promesa retornada quan una trucada falla — per exemple, quan la referència de connexió no es pot resoldre, la connexió no està autoritzada i l'usuari no completa la sol·licitud de consentiment, o el connector retorna un estat d'error. executeConnectorOperation es resol amb ok: false per a la majoria d'estats d'error, però encara rebutja per una operació perduda, una connexió no autoritzada (403) sense consentiment complet, o una fallada de transport. Embolica les trucades connectors a try/catch.

Mètode	Descripció
createConnectorRow	Crea una nova fila a la taula de connectors especificada.
deleteConnectorRow	Elimina una fila de la taula de connectors especificada.
executeConnectorOperation	Invoca una operació amb nom exposada per un connector REST (clau d'operació), com ara Office 365 Users.
getConnectorSwagger	Recupera la definició de Swagger (OpenAPI) per al connector.
getConnectorTableSchema	Recupera l'esquema d'una taula (també anomenada entitat o llista) exposada pel connector.
listConnectorDatasets	Llista els conjunts de dades disponibles per al connector.
listConnectorOperations	Llista les operacions exposades per un connector REST (clau d'operació).
listConnectorTables	Llista les taules disponibles en el conjunt de dades de connectors especificat.
queryConnectorTable	Consulta una taula exposada pel connector amb les opcions especificades.
retrieveConnectorRow	Recupera una sola fila de la taula de connectors especificada.
updateConnectorRow	Actualitza una fila existent a la taula de connectors especificada.

queryConnectorTable mètode

Consulta una taula exposada pel connector utilitzant les opcions especificades.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió vinculat a la pàgina (per exemple, sp_shared_sharepointonline).
dataset	string	El conjunt de dades que conté la taula, com ara una URL d'un lloc de SharePoint.
tableName	string	El nom intern de la taula, a partir de la name propietat retornada per listConnectorTables. No facis servir el nom de mostra.
options	QueryConnectorTableOptions	Opcions per consultar la taula.

QueryConnectorTableOptions

Nom	Tipus	Descripció
select	string[]	(Recomanat) Array de noms de columnes per recuperar.
filter	string	(Opcional) Expressió del filtre suportada pel connector.
orderBy	string	(Opcional) Ordre per expressió suportat pel connector.
top	number	(Opcional) Nombre màxim de files per tornar.

Devolucions

Una promesa que conté el resultat de l'operació. Quan l'operació té èxit, la promesa retorna un objecte que conté una taula de dades amb els resultats amb aquestes propietats:

Nom	Tipus	Descripció
rows	Object[]	Array de dades de files.
hasMoreRows	boolean	Indica si hi ha més files disponibles.

queryConnectorTable retorna una sola pàgina de resultats. No retorna cap funció de continuació, i actualment no hi ha cap manera compatible d'obtenir la pàgina següent. Quan hasMoreRows és true, més files coincidien de les que es van retornar. Restringiu la consulta a filter, o digueu a l'usuari que els resultats són incomplets.

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

Els exemples següents assumeixen documentsTableName que conté les taules name de listConnectorTables, com s'ha mostrat anteriorment.

listConnectorTables mètode

Llista les taules (llistes o entitats) disponibles en el conjunt de dades de connectors especificat.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
dataset	string	El conjunt de dades per llistar taules.

Devolucions

Una promesa que conté una sèrie d'informació de taula. Cada entrada té aquestes propietats:

Nom	Tipus	Descripció
name	string	El nom intern de la taula.
displayName	string	El nom de la taula.

Exemple de listConnectorTables

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

listConnectorDatasets mètode

Llista els conjunts de dades disponibles per al connector, com ara els llocs de SharePoint als quals una connexió pot accedir.

Paràmetres

Estableix un valor per a aquest paràmetre requerit.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.

Devolucions

Una promesa que conté una sèrie d'informació del conjunt de dades. Cada entrada té aquestes propietats:

Nom	Tipus	Descripció
name	string	El nom intern o identificador del conjunt de dades.
displayName	string	El nom de visualització del conjunt de dades.

Exemple de listConnectorDatasets

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

listConnectorOperations mètode

Llista les operacions definides a la definició de Swagger del connector, excloent les operacions marcades com a internes, ordenades per nom de visualització. Aquest mètode és més útil per a connectors REST (operation-keyed) com Office 365 Users. Per als connectors tabulars, utilitza els mètodes de consulta i fila en lloc de les operacions que llista aquest mètode.

Paràmetres

Estableix un valor per a aquest paràmetre requerit.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.

Devolucions

Una promesa que conté una sèrie d'informació d'operacions. Cada entrada té aquestes propietats:

Nom	Tipus	Descripció
name	string	L'ID de l'operació tal com es defineix en la definició de Swagger del connector. Passa aquest valor a executeConnectorOperation.
displayName	string	El nom de l'operació llegible per a l'humà per a la pantalla, com ara el resum de Swagger. Torna a si name no hi ha cap resum definit.

Exemple de listConnectorOperations

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

getConnectorSwagger mètode

Recupera la definició de Swagger (OpenAPI) per al connector, que descriu les operacions que exposa. El document retornat descriu el connector en conjunt. No inclou esquemes de columna per taula per als connectors tabulars. Utilitza getConnectorTableSchema aquesta informació.

Paràmetres

Estableix un valor per a aquest paràmetre requerit.

Nom	Tipus	Descripció
connectorApiId	string	L'identificador de l'API del connector, com /providers/Microsoft.PowerApps/apis/shared_sharepointonlineara . Aquest identificador és diferent del nom lògic de referència de connexió (connectorLogicalName) utilitzat per la majoria d'altres mètodes de connectors.

Devolucions

Una promesa que conté la definició de Swagger del connector com a objecte.

Exemple 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 mètode

Recupera l'esquema (definicions de columnes) d'una taula exposada pel connector. El connector defineix l'esquema que retorna, i varia segons el connector. No assumeixis que inclou totes les columnes dinàmiques que pugui contenir una taula.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
dataset	string	El conjunt de dades que conté la taula.
tableName	string	El nom intern de la taula, a partir de la name propietat retornada per listConnectorTables. No facis servir el nom de mostra.

Devolucions

Una promesa que conté l'esquema de la taula com a objecte.

Exemple de 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 mètode

Recupera una sola fila de la taula de connectors especificada.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
dataset	string	El conjunt de dades que conté la taula.
tableName	string	El nom intern de la taula, a partir de la name propietat retornada per listConnectorTables. No facis servir el nom de mostra.
id	string	L'ID de la fila a recuperar.
options	RetrieveConnectorRowOptions	(Opcional) Opcions per recuperar la fila.

RetrieveConnectorRowOptions

Nom	Tipus	Descripció
select	string[]	(Recomanat) Array de noms de columnes per recuperar. Si s'omet, no s'envia cap $select projecció — el connector determina quines columnes retornar i no garanteix retornar cada columna de la fila.

Devolucions

Una promesa que conté les dades de la fila.

exemple 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 mètode

Crea una nova fila a la taula de connectors especificada.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
dataset	string	El conjunt de dades que conté la taula.
tableName	string	El nom intern de la taula, a partir de la name propietat retornada per listConnectorTables. No facis servir el nom de mostra.
row	object	Les dades de la fila a crear.

Devolucions

Una promesa que conté el cos de resposta retornat pel connector, si n'hi ha. Depenent del connector, aquest valor pot ser la fila creada, una fila parcial o cap valor.

Exemple 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 mètode

Actualitza una fila existent a la taula de connectors especificada.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
dataset	string	El conjunt de dades que conté la taula.
tableName	string	El nom intern de la taula, a partir de la name propietat retornada per listConnectorTables. No facis servir el nom de mostra.
id	string	L'ID de la fila per actualitzar.
row	object	Les dades de la fila a actualitzar.

Devolucions

Una promesa que conté el cos de resposta retornat pel connector, si n'hi ha. Depenent del connector, aquest valor pot ser la fila actualitzada, una fila parcial o cap valor. Per llegir els valors actuals de la fila, crida retrieveConnectorRow.

Exemple de 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 mètode

Elimina una fila de la taula de connectors especificada.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
dataset	string	El conjunt de dades que conté la taula.
tableName	string	El nom intern de la taula, a partir de la name propietat retornada per listConnectorTables. No facis servir el nom de mostra.
id	string	L'ID de la fila per esborrar.

Devolucions

Una promesa que conté el resultat de l'operació. Quan l'operació té èxit, no retorna cap valor.

exemple 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 mètode

Invoca una operació amb nom exposada per un connector REST (clau d'operació), com ara HTTP, Teams send-message o Office 365 Users. Els connectors tabulars haurien d'utilitzar els mètodes CRUD de consulta i fila en comptes d'això.

Paràmetres

Estableix valors per a aquests paràmetres requerits.

Nom	Tipus	Descripció
connectorLogicalName	string	El nom lògic de la referència de connexió està vinculat a la pàgina.
operationName	string	L'ID de l'operació tal com es defineix en la definició de Swagger del connector.
parameters	object	Els paràmetres requerits per l'operació. Passa un objecte buit ({}) si l'operació no pren paràmetres — aquest paràmetre és necessari fins i tot quan no hi ha res per enviar.

Devolucions

Una promesa que conté el resultat de l'operació amb aquestes propietats. La promesa es rebutja si la referència de connexió no es pot resoldre, la definició de Swagger del connector no es pot recuperar, l'operació no es troba en aquesta, la trucada no es pot despagar, o la connexió no està autoritzada (HTTP 403) i l'usuari no completa la sol·licitud de consentiment de connexió.

Nom	Tipus	Descripció
ok	boolean	true quan l'estat HTTP subjacent és inferior a 400. Aquest estat inclou els estats de redirecció (3xx), així que no tracteu ok només com a prova que l'operació ha retornat dades — també comproveu status o inspeccioneu body.
status	number	El codi d'estat HTTP en brut retornat pel connector.
body	unknown	El cos de resposta JSON analitzat, o la cadena en brut si el cos no és JSON.

Exemple d'executeConnectorOperation

L'exemple següent assumeix una operació anomenada CopyFile que accepta sourceUrl i destinationUrl paràmetres. Verifica l'ID d'operació i els seus paràmetres amb la pròpia definició de Swagger del connector (per exemple, amb listConnectorOperations o getConnectorSwagger) abans d'utilitzar-lo, ja que les operacions disponibles i els seus paràmetres varien segons el connector.

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