Métodos de conector para páginas gerativas

Use os métodos de conector do dataApi objeto para trabalhar com dados expostos por um conector do Power Platform associado à página.

Observação

Os métodos de conector são opcionais no contrato compartilhado dataApi . Alguns hosts não os implementam, portanto, verifique se existe um método antes de chamá-lo. Um método presente não significa que a página tenha um conector associado a ela ou que a conexão, o conjunto de dados, a tabela ou a operação estejam configuradas, autorizadas ou permitidas conforme o esperado.

Ao contrário dos métodos de ação e função, os métodos de conector rejeitam a promessa retornada quando uma chamada falha – por exemplo, quando a referência de conexão não pode ser resolvida, a conexão não é autorizada e o usuário não conclui o prompt de consentimento ou o conector retorna um status de erro. executeConnectorOperation resolve com ok: false a maioria dos status de erro, mas ainda rejeita uma operação ausente, uma conexão não autorizada (403) sem consentimento concluído ou uma falha de transporte. Encapsular chamadas de conector em try/catch.

Método	Description
createConnectorRow	Cria uma nova linha na tabela de conectores especificada.
deleteConnectorRow	Exclui uma linha da tabela de conectores especificada.
executeConnectorOperation	Invoca uma operação nomeada exposta por um conector REST (chave de operação), como Usuários do Office 365.
getConnectorSwagger	Recupera a definição de Swagger (OpenAPI) para o conector.
getConnectorTableSchema	Recupera o esquema de uma tabela (também chamada de entidade ou lista) exposta pelo conector.
listConnectorDatasets	Lista os conjuntos de dados disponíveis para o conector.
listConnectorOperations	Lista as operações expostas por um conector REST (chave de operação).
listConnectorTables	Lista as tabelas disponíveis no conjunto de dados do conector especificado.
queryConnectorTable	Consulta uma tabela exposta pelo conector com as opções especificadas.
retrieveConnectorRow	Recupera uma única linha da tabela do conector especificada.
updateConnectorRow	Atualiza uma linha existente na tabela do conector especificada.

método queryConnectorTable

Consulta uma tabela exposta pelo conector usando as opções especificadas.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página (por exemplo, sp_shared_sharepointonline).
dataset	string	O conjunto de dados que contém a tabela, como uma URL do site SharePoint.
tableName	string	O nome interno da tabela, da name propriedade retornada por listConnectorTables. Não use o nome de exibição.
options	QueryConnectorTableOptions	Opções para consultar a tabela.

QueryConnectorTableOptions

Name	Tipo	Description
select	string[]	(Recomendado) Matriz de nomes de coluna a serem recuperados.
filter	string	(Opcional) Expressão de filtro compatível com o conector.
orderBy	string	(Opcional) Expressão order-by compatível com o conector.
top	number	(Opcional) Número máximo de linhas a serem retornadas.

Returns

Uma promessa que contém o resultado da operação. Quando a operação for bem-sucedida, a promessa retornará um objeto que contém uma tabela de dados com os resultados com estas propriedades:

Name	Tipo	Description
rows	Object[]	Matriz de dados de linha.
hasMoreRows	boolean	Indica se há mais linhas disponíveis.

queryConnectorTable retorna uma única página de resultados. Ele não retorna uma função de continuação e, no momento, não há nenhuma maneira compatível de buscar a próxima página. Quando hasMoreRows é true, mais linhas correspondem do que foram retornadas. Restrinja a consulta filterou informe ao usuário que os resultados estão incompletos.

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

Os exemplos a seguir pressupõem documentsTableName que contém a tabela de namelistConnectorTables, conforme mostrado acima.

método listConnectorTables

Lista as tabelas (listas ou entidades) disponíveis no conjunto de dados do conector especificado.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
dataset	string	O conjunto de dados para o qual listar tabelas.

Returns

Uma promessa que contém uma matriz de informações de tabela. Cada entrada tem estas propriedades:

Name	Tipo	Description
name	string	O nome interno da tabela.
displayName	string	O nome de exibição da tabela.

Exemplo de listConnectorTables

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

método listConnectorDatasets

Lista os conjuntos de dados disponíveis para o conector, como os sites SharePoint que uma conexão pode acessar.

Parameters

Defina um valor para esse parâmetro necessário.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.

Returns

Uma promessa que contém uma matriz de informações do conjunto de dados. Cada entrada tem estas propriedades:

Name	Tipo	Description
name	string	O nome interno ou o identificador do conjunto de dados.
displayName	string	O nome de exibição do conjunto de dados.

exemplo de listConnectorDatasets

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

método listConnectorOperations

Lista as operações definidas na definição swagger do conector, excluindo operações marcadas como internas, classificadas pelo nome de exibição. Esse método é mais útil para conectores REST (chave de operação), como Usuários do Office 365. Para conectores tabulares, use os métodos de consulta e linha em vez das operações que esse método lista.

Parameters

Defina um valor para esse parâmetro necessário.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.

Returns

Uma promessa que contém uma matriz de informações de operação. Cada entrada tem estas propriedades:

Name	Tipo	Description
name	string	A ID da operação, conforme definido na definição do Swagger do conector. Passe esse valor para executeConnectorOperation.
displayName	string	O nome da operação legível para exibição, como o resumo do Swagger. Retornará se name nenhum resumo for definido.

exemplo de listConnectorOperations

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

método getConnectorSwagger

Recupera a definição de Swagger (OpenAPI) para o conector, que descreve as operações que ele expõe. O documento retornado descreve o conector geral. Ele não inclui esquemas de coluna por tabela para conectores tabulares. Use getConnectorTableSchema para essas informações.

Parameters

Defina um valor para esse parâmetro necessário.

Name	Tipo	Description
connectorApiId	string	O identificador da API do conector, como /providers/Microsoft.PowerApps/apis/shared_sharepointonline. Esse identificador é diferente do nome lógico de referência de conexão (connectorLogicalName) usado pela maioria dos outros métodos de conector.

Returns

Uma promessa que contém a definição swagger do conector como um objeto.

exemplo 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 o esquema (definições de coluna) para uma tabela exposta pelo conector. O conector define o esquema retornado e varia de acordo com o conector. Não suponha que ela inclua todas as colunas dinâmicas que uma tabela possa conter.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
dataset	string	O conjunto de dados que contém a tabela.
tableName	string	O nome interno da tabela, da name propriedade retornada por listConnectorTables. Não use o nome de exibição.

Returns

Uma promessa que contém o esquema da tabela como um objeto.

Exemplo 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 uma única linha da tabela do conector especificada.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
dataset	string	O conjunto de dados que contém a tabela.
tableName	string	O nome interno da tabela, da name propriedade retornada por listConnectorTables. Não use o nome de exibição.
id	string	A ID da linha a ser recuperada.
options	RetrieveConnectorRowOptions	(Opcional) Opções para recuperar a linha.

RetrieveConnectorRowOptions

Name	Tipo	Description
select	string[]	(Recomendado) Matriz de nomes de coluna a serem recuperados. Se omitido, nenhuma $select projeção será enviada – o conector determinará quais colunas retornarão e não garantirá o retorno de todas as colunas na linha.

Returns

Uma promessa que contém os dados da linha.

exemplo 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

Cria uma nova linha na tabela de conectores especificada.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
dataset	string	O conjunto de dados que contém a tabela.
tableName	string	O nome interno da tabela, da name propriedade retornada por listConnectorTables. Não use o nome de exibição.
row	object	Os dados de linha a serem criados.

Returns

Uma promessa que contém o corpo da resposta retornado pelo conector, se houver. Dependendo do conector, esse valor pode ser a linha criada, uma linha parcial ou nenhum valor.

exemplo 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

Atualiza uma linha existente na tabela do conector especificada.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
dataset	string	O conjunto de dados que contém a tabela.
tableName	string	O nome interno da tabela, da name propriedade retornada por listConnectorTables. Não use o nome de exibição.
id	string	A ID da linha a ser atualizada.
row	object	Os dados de linha a serem atualizados.

Returns

Uma promessa que contém o corpo da resposta retornado pelo conector, se houver. Dependendo do conector, esse valor pode ser a linha atualizada, uma linha parcial ou nenhum valor. Para ler os valores atuais da linha, chame retrieveConnectorRow.

Exemplo 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

Exclui uma linha da tabela de conectores especificada.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
dataset	string	O conjunto de dados que contém a tabela.
tableName	string	O nome interno da tabela, da name propriedade retornada por listConnectorTables. Não use o nome de exibição.
id	string	A ID da linha a ser excluída.

Returns

Uma promessa que contém o resultado da operação. Quando a operação é bem-sucedida, ela não retorna nenhum valor.

Exemplo 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 uma operação nomeada exposta por um conector REST (chave de operação), como HTTP, mensagem de envio do Teams ou Usuários do Office 365. Em vez disso, os conectores tabulares devem usar os métodos CRUD de consulta e linha.

Parameters

Defina valores para esses parâmetros necessários.

Name	Tipo	Description
connectorLogicalName	string	O nome lógico da referência de conexão associada à página.
operationName	string	A ID da operação, conforme definido na definição do Swagger do conector.
parameters	object	Os parâmetros exigidos pela operação. Passe um objeto vazio ({}) se a operação não tiver parâmetros – esse parâmetro é necessário mesmo quando não há nada para enviar.

Returns

Uma promessa que contém o resultado da operação com essas propriedades. A promessa rejeitará se a referência de conexão não puder ser resolvida, a definição do Swagger do conector não puder ser recuperada, a operação não for encontrada nela, a chamada não puder ser expedida ou a conexão não estiver autorizada (HTTP 403) e o usuário não concluir o prompt de consentimento da conexão.

Name	Tipo	Description
ok	boolean	true quando o status HTTP subjacente for menor que 400. Esse status inclui status de redirecionamento (3xx), portanto, não trate ok sozinho como prova de que os dados retornados pela operação também verificam status ou inspecionam body.
status	number	O código de status HTTP bruto retornado pelo conector.
body	unknown	O corpo da resposta JSON analisado ou a cadeia de caracteres bruta se o corpo não for JSON.

exemplo de executeConnectorOperation

O exemplo a seguir pressupõe uma operação nomeada CopyFile que aceita sourceUrl e destinationUrl parâmetros. Verifique a ID da operação e seus parâmetros em relação à própria definição do Swagger do conector (por exemplo, com ou getConnectorSwagger) antes de usá-la, já que as operações disponíveis e seus parâmetros variam de acordo com listConnectorOperations o 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);
}