Métodos de conector para páginas generativas

Use los métodos de conector del dataApi objeto para trabajar con los datos expuestos por un conector de Power Platform enlazado a la página.

Note

Los métodos del conector son opcionales en el contrato compartido dataApi . Algunos hosts no los implementan, por lo que debe comprobar que existe un método antes de llamarlo. Un método que está presente no significa que la página tenga un conector enlazado a él o que la conexión, el conjunto de datos, la tabla o la operación estén configurados, autorizados o permitidos según lo previsto.

A diferencia de los métodos de acción y función, los métodos del conector rechazan la promesa devuelta cuando se produce un error en una llamada, por ejemplo, cuando no se puede resolver la referencia de conexión, la conexión no está autorizada y el usuario no completa la solicitud de consentimiento o el conector devuelve un estado de error. executeConnectorOperation resuelve con ok: false para la mayoría de los estados de error, pero sigue rechazando una operación que falta, una conexión no autorizada (403) sin consentimiento completado o un error de transporte. Ajuste las llamadas del conector en try/catch.

Método	Description
createConnectorRow	Crea una nueva fila en la tabla de conectores especificada.
deleteConnectorRow	Elimina una fila de la tabla de conectores especificada.
executeConnectorOperation	Invoca una operación con nombre expuesta por un conector REST (con clave de operación), como Usuarios de Office 365.
getConnectorSwagger	Recupera la definición de Swagger (OpenAPI) para el conector.
getConnectorTableSchema	Recupera el esquema de una tabla (también denominada entidad o lista) expuesta por el conector.
listConnectorDatasets	Enumera los conjuntos de datos disponibles para el conector.
listConnectorOperations	Enumera las operaciones expuestas por un conector REST (con claves de operación).
listConnectorTables	Enumera las tablas disponibles en el conjunto de datos del conector especificado.
queryConnectorTable	Consulta una tabla expuesta por el conector con las opciones especificadas.
retrieveConnectorRow	Recupera una sola fila de la tabla de conectores especificada.
updateConnectorRow	Actualiza una fila existente en la tabla de conectores especificada.

método queryConnectorTable

Consulta una tabla expuesta por el conector mediante las opciones especificadas.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página (por ejemplo, sp_shared_sharepointonline).
dataset	string	Conjunto de datos que contiene la tabla, como una dirección URL de sitio SharePoint.
tableName	string	Nombre interno de la tabla, de la name propiedad devuelta por listConnectorTables. No use el nombre para mostrar.
options	QueryConnectorTableOptions	Opciones para consultar la tabla.

QueryConnectorTableOptions

Name	Tipo	Description
select	string[]	(Recomendado) Matriz de nombres de columna que se van a recuperar.
filter	string	(Opcional) Expresión de filtro compatible con el conector.
orderBy	string	(Opcional) Expresión order-by compatible con el conector.
top	number	(Opcional) Número máximo de filas que se van a devolver.

Devoluciones

Promesa que contiene el resultado de la operación. Cuando la operación se realiza correctamente, la promesa devuelve un objeto que contiene una tabla de datos con los resultados con estas propiedades:

Name	Tipo	Description
rows	Object[]	Matriz de datos de fila.
hasMoreRows	boolean	Indica si hay más filas disponibles.

queryConnectorTable devuelve una sola página de resultados. No devuelve una función de continuación y actualmente no hay ninguna manera admitida de capturar la página siguiente. Cuando hasMoreRows es true, se devolvieron más filas que las devueltas. Restrinja la consulta con filtero indique al usuario que los resultados están incompletos.

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

En los ejemplos siguientes se supone documentsTableName que contiene la tabla name de listConnectorTables, como se muestra anteriormente.

método listConnectorTables

Enumera las tablas (listas o entidades) disponibles en el conjunto de datos del conector especificado.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
dataset	string	Conjunto de datos para el que se van a enumerar las tablas.

Devoluciones

Promesa que contiene una matriz de información de tabla. Cada entrada tiene estas propiedades:

Name	Tipo	Description
name	string	Nombre interno de la tabla.
displayName	string	Nombre para mostrar de la tabla.

Ejemplo de listConnectorTables

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

método listConnectorDatasets

Enumera los conjuntos de datos disponibles para el conector, como los sitios de SharePoint a los que puede acceder una conexión.

Parameters

Establezca un valor para este parámetro necesario.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.

Devoluciones

Promesa que contiene una matriz de información del conjunto de datos. Cada entrada tiene estas propiedades:

Name	Tipo	Description
name	string	Nombre interno o identificador del conjunto de datos.
displayName	string	Nombre para mostrar del conjunto de datos.

Ejemplo de listConnectorDatasets

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

método listConnectorOperations

Enumera las operaciones definidas en la definición de Swagger del conector, excepto las operaciones marcadas como internas, ordenadas por nombre para mostrar. Este método es más útil para conectores REST (con clave de operación), como Usuarios de Office 365. En el caso de los conectores tabulares, use los métodos de consulta y fila en lugar de las operaciones que muestra este método.

Parameters

Establezca un valor para este parámetro necesario.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.

Devoluciones

Promesa que contiene una matriz de información de operación. Cada entrada tiene estas propiedades:

Name	Tipo	Description
name	string	Identificador de operación tal como se define en la definición de Swagger del conector. Pase este valor a executeConnectorOperation.
displayName	string	Nombre de la operación legible para mostrar, como el resumen de Swagger. Vuelve a name si no se define ningún resumen.

Ejemplo de listConnectorOperations

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

método getConnectorSwagger

Recupera la definición de Swagger (OpenAPI) para el conector, que describe las operaciones que expone. El documento devuelto describe el conector en general. No incluye esquemas de columna por tabla para conectores tabulares. Use getConnectorTableSchema para esa información.

Parameters

Establezca un valor para este parámetro necesario.

Name	Tipo	Description
connectorApiId	string	Identificador de API del conector, como /providers/Microsoft.PowerApps/apis/shared_sharepointonline. Este identificador es diferente del nombre lógico de referencia de conexión (connectorLogicalName) usado por la mayoría de los demás métodos de conector.

Devoluciones

Promesa que contiene la definición de Swagger del conector como un objeto .

Ejemplo de 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"
);

método getConnectorTableSchema

Recupera el esquema (definiciones de columna) de una tabla expuesta por el conector. El conector define el esquema que devuelve y varía según el conector. No suponga que incluye todas las columnas dinámicas que puede contener una tabla.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
dataset	string	Conjunto de datos que contiene la tabla.
tableName	string	Nombre interno de la tabla, de la name propiedad devuelta por listConnectorTables. No use el nombre para mostrar.

Devoluciones

Promesa que contiene el esquema de la tabla como un objeto .

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

método retrieveConnectorRow

Recupera una sola fila de la tabla de conectores especificada.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
dataset	string	Conjunto de datos que contiene la tabla.
tableName	string	Nombre interno de la tabla, de la name propiedad devuelta por listConnectorTables. No use el nombre para mostrar.
id	string	Identificador de la fila que se va a recuperar.
options	RetrieveConnectorRowOptions	(Opcional) Opciones para recuperar la fila.

RetrieveConnectorRowOptions

Name	Tipo	Description
select	string[]	(Recomendado) Matriz de nombres de columna que se van a recuperar. Si se omite, no se envía ninguna $select proyección: el conector determina qué columnas se van a devolver y no garantiza que devuelva todas las columnas de la fila.

Devoluciones

Promesa que contiene los datos de fila.

Ejemplo de 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"
);

método createConnectorRow

Crea una nueva fila en la tabla de conectores especificada.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
dataset	string	Conjunto de datos que contiene la tabla.
tableName	string	Nombre interno de la tabla, de la name propiedad devuelta por listConnectorTables. No use el nombre para mostrar.
row	object	Datos de fila que se van a crear.

Devoluciones

Promesa que contiene el cuerpo de respuesta devuelto por el conector, si existe. Dependiendo del conector, este valor puede ser la fila creada, una fila parcial o ningún valor.

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

método updateConnectorRow

Actualiza una fila existente en la tabla de conectores especificada.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
dataset	string	Conjunto de datos que contiene la tabla.
tableName	string	Nombre interno de la tabla, de la name propiedad devuelta por listConnectorTables. No use el nombre para mostrar.
id	string	Identificador de la fila que se va a actualizar.
row	object	Datos de fila que se van a actualizar.

Devoluciones

Promesa que contiene el cuerpo de respuesta devuelto por el conector, si existe. Según el conector, este valor puede ser la fila actualizada, una fila parcial o ningún valor. Para leer los valores actuales de la fila, llame a retrieveConnectorRow.

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

método deleteConnectorRow

Elimina una fila de la tabla de conectores especificada.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
dataset	string	Conjunto de datos que contiene la tabla.
tableName	string	Nombre interno de la tabla, de la name propiedad devuelta por listConnectorTables. No use el nombre para mostrar.
id	string	Identificador de la fila que se va a eliminar.

Devoluciones

Promesa que contiene el resultado de la operación. Cuando la operación se realiza correctamente, no devuelve ningún valor.

Ejemplo de 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"
);

método executeConnectorOperation

Invoca una operación con nombre expuesta por un conector REST (con clave de operación), como HTTP, mensaje de envío de Teams o Usuarios de Office 365. En su lugar, los conectores tabulares deben usar los métodos CRUD de consulta y fila.

Parameters

Establezca valores para estos parámetros necesarios.

Name	Tipo	Description
connectorLogicalName	string	Nombre lógico de la referencia de conexión enlazada a la página.
operationName	string	Identificador de operación tal como se define en la definición de Swagger del conector.
parameters	object	Parámetros requeridos por la operación. Pase un objeto vacío ({}) si la operación no toma parámetros; este parámetro es necesario incluso cuando no hay nada que enviar.

Devoluciones

Promesa que contiene el resultado de la operación con estas propiedades. La promesa rechaza si no se puede resolver la referencia de conexión, la definición de Swagger del conector no se puede recuperar, la operación no se encuentra en ella, la llamada no se puede enviar o la conexión no está autorizada (HTTP 403) y el usuario no completa la solicitud de consentimiento de conexión.

Name	Tipo	Description
ok	boolean	true cuando el estado HTTP subyacente es menor que 400. Este estado incluye los estados de redirección (3xx), por lo que no trate ok solo como prueba de la operación los datos devueltos; también compruebe o inspeccione statusbody.
status	number	Código de estado HTTP sin procesar devuelto por el conector.
body	unknown	Cuerpo de respuesta JSON analizado o cadena sin formato si el cuerpo no es JSON.

Ejemplo executeConnectorOperation

En el ejemplo siguiente se presupone una operación denominada CopyFile que acepta parámetros sourceUrl y destinationUrl . Compruebe el identificador de operación y sus parámetros en la propia definición de Swagger del conector (por ejemplo, con listConnectorOperations o getConnectorSwagger) antes de usarlo, ya que las operaciones disponibles y sus parámetros varían según el 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);
}