APIs do cliente Power Pages (versão prévia)

[Este artigo é uma documentação de pré-lançamento e está sujeito a alterações.]

Power Pages APIs de cliente ajudam os desenvolvedores a manipular componentes de interface do usuário, gerenciar formulários e listas, manipular a autenticação do usuário e interagir com registros do Dataverse programaticamente. A API do cliente fica disponível quando sua página é carregada e pode ser acessada por meio de uma variável global com um nome que você escolher.

Este artigo usa o nome $pages da variável em todos os exemplos e recomenda que você siga esta convenção de nomenclatura para consistência.

Com as APIs do cliente, você pode:

Com a $pages API do cliente, você pode:

• Recuperar e modificar formulários e controles de formulário
• Mostrar ou ocultar elementos da interface do usuário
• Criar e recuperar registros usando a API Web
• Gerenciar a autenticação do usuário
• Trabalhar com conteúdo multilíngue

Inicialização da API do cliente

A $pages API do cliente não é inicializada imediatamente quando a página é carregada. Use a Microsoft.Dynamic365.Portal.onPagesClientApiReady função para atribuir o objeto de API à $pages variável. Existem duas maneiras de inicializar a API do cliente:

Preparação da API baseada em retorno de chamada

Use uma função de retorno de chamada que atribua o objeto de API a uma variável que você definir quando estiver pronta. Dois exemplos mostram como:

Usando uma função anônima:

Microsoft.Dynamic365.Portal.onPagesClientApiReady(($pages) => {
    const forms = $pages.currentPage.forms.getAll();
    console.log(`Found ${forms.length} forms on the page.`);
});

Usando uma função nomeada:

function start($pages){
    const forms = $pages.currentPage.forms.getAll();
    console.log(`Found ${forms.length} forms on the page.`);
}

Microsoft.Dynamic365.Portal.onPagesClientApiReady(start)

Preparação da API baseada em promessa/espera

Usa await para lidar com a promessa retornada pela Microsoft.Dynamic365.Portal.onPagesClientApiReady função para um fluxo assíncrono mais limpo.

let $pages = await Microsoft.Dynamic365.Portal.onPagesClientApiReady();
const forms = $pages.currentPage.forms.getAll();
console.log(`Found ${forms.length} forms on the page.`);

Quando usar cada abordagem

A tabela a seguir descreve quando usar cada abordagem.

Coleção $pages.currentPage.forms

A $pages.currentPage.forms coleção inclui métodos para trabalhar com elementos de formulário na página.

Métodos $pages.currentPage.forms

Use esses métodos para listar formulários e obter instâncias de formulário específicas.

Exemplos do método $pages.currentPage.forms

Esses exemplos mostram como obter todos os formulários e recuperar formulários específicos por ID ou nome.

let forms = $pages.currentPage.forms.getAll();
let form1 = $pages.currentPage.forms.getFormById('form_#1');
let form2 = $pages.currentPage.forms.getFormByName('form_name')

Interface IForm

A IForm interface representa um contêiner para controles e guias.

Propriedades IForm

As propriedades a seguir descrevem o formulário e seus controles e guias contidos.

Métodos IForm

Use esses métodos para consultar a visibilidade de um formulário e alternar se ele está visível.

Exemplo de IForm

O exemplo a seguir recupera um formulário por ID e registra sua visibilidade, número de controles e guias.

let form = $pages.currentPage.forms.getFormById('form_#1');

console.log(`Form id: ${form.id} has ${form.controls.length} controls.`); 

if (form.getVisible()) {  
console.log('Form is currently visible.');  
}  
let tabs = form.tabs;  
console.log(`Form has ${tabs.length} tabs.`);

Formulário de várias etapas

Um formulário de várias etapas é um contêiner que contém vários formulários básicos.

Propriedades do formulário de várias etapas

As propriedades a seguir se aplicam ao contêiner de formulário de várias etapas e descrevem o que está disponível na etapa ativa atualmente.

Métodos de formulário de várias etapas

Use esses métodos para verificar a visibilidade e mover-se entre as etapas em um formulário de várias etapas.

Exemplo de formulário de várias etapas

Este exemplo mostra como recuperar um formulário de várias etapas, inspecioná-lo e avançar para a próxima etapa.

let $pages = await Microsoft.Dynamic365.Portal.onPagesClientApiReady();
let form = $pages.currentPage.forms.getFormById('multiform_#1');
console.log(`Form id: ${form.id} has ${form.controls.length} controls.`);

if (form.getVisible()) {
console.log('Form is currently visible.');
}

let tabs = form.tabs;
console.log(`Form has ${tabs.length} tabs.`);

form.goToNextStep();  

Tab

Um Tab contém uma ou mais seções em um formulário.

Propriedade Tab Sections

Uma matriz de seções dentro da guia.

Métodos tab

Use esses métodos para verificar a visibilidade de uma guia, recuperar seu nome e alternar se ela está visível.

Exemplo de guia

Este exemplo recupera um formulário, enumera suas guias e registra o nome da primeira guia.

let form = $pages.currentPage.forms.getFormById('form_#1');  
let tabs = form.tabs;  
console.log(`Form has ${tabs.length} tabs.`);  
console.log(`First tab is named: ${tabs[0].getName()}`);  

Seção

Controles de grupo de seções em uma guia.

Propriedade Section Controls

Uma matriz de controles dentro da seção.

Métodos de seção

Use esses métodos para ler o nome de uma seção e controlar sua visibilidade.

Exemplo de seção

Este exemplo recupera seções da primeira guia de um formulário e registra detalhes básicos.

let form = $pages.currentPage.forms.getFormById('form_#1');  
let sections = form.tabs[0].sections;  
console.log(`Tab has ${sections.length} section(s).`);  
console.log(`First section is named: ${sections[0].getName()}`);

Control

Os controles representam elementos de formulário individuais.

Métodos de controle

Use esses métodos para recuperar ou atualizar o valor, a visibilidade e o estado desabilitado de um controle.

Exemplo de controle

Este exemplo busca um formulário, verifica a visibilidade do primeiro controle e o oculta.

let form = $pages.currentPage.forms.getFormById('form_#1');  
let controls = form.controls;  
if (controls.length > 0) {  
if (controls[0].getVisible()) {  
console.log(`Control ${controls[0].getName()} is visible.`);  
}  
controls[0].setVisible(false); // Hide the first control.  
}

Controles com suporte

Todos os controles implementam os métodos de controle padrão. Alguns controles fornecem mais métodos e têm detalhes de implementação diferentes dos métodos de controle padrão. Saiba mais sobre outros métodos e diferenças de implementação para diferentes tipos de controles.

coleção $pages.currentPage.lists

A coleção de listas fornece métodos para trabalhar com elementos de lista tradicionais e modernos na página.

Métodos $pages.currentPage.lists

Use esses métodos para enumerar todas as listas na página e obter uma lista específica pela ID do elemento HTML.

exemplos de $pages.currentPage.lists

Esses exemplos mostram como enumerar todas as listas na página e obter uma lista específica por sua ID de elemento HTML.

let lists = $pages.currentPage.lists.getAll();
let list = $pages.currentPage.lists.getListById('list_#1');

Interface IList

Uma lista representa um componente de dados tabular ou semelhante à grade.

Propriedades de IList

Essas propriedades identificam a lista e indicam se ela usa o modelo de renderização moderno.

Métodos IList

Use esses métodos para verificar a visibilidade da lista, alternar se ela está visível e acessar o elemento HTML subjacente.

Exemplo de IList

O exemplo a seguir recupera uma lista por ID e registra seu status de visibilidade.

let list = $pages.currentPage.lists.getListById('list_#1');  
console.log(`List id: ${list.id}`);  
if (list.getVisible()) {  
console.log('List is currently visible.');  
}

objeto $pages.user

O $pages.user objeto fornece métodos para conectar ou sair o usuário.

métodos $pages.user

Esses métodos não retornam nenhum valor.

objeto $pages.webAPI

O $pages.webAPI objeto fornece métodos para criar e recuperar registros de uma fonte de dados.

Método createRecord

Cria um novo registro na tabela especificada.

Sintaxe: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<object>
Retorna: uma promessa que é resolvida para o registro criado ou o resultado da operação.

Parâmetros do método createRecord

Forneça a tabela de destino e o objeto de dados que representa o registro a ser criado.

exemplo do método createRecord

Este exemplo demonstra a chamada createRecord com um nome de conjunto de entidades e um objeto de dados mínimo.

$pages.webAPI.createRecord('contacts', {  
firstName: 'User',
lastName: 'Test'  
});

Método retrieveRecord

Recupera um registro por seu identificador exclusivo.

Sintaxe: $pages.webAPI.retrieveRecord(entitySetName: string, id: string, options?: string): Promise<object>
Retorna: uma promessa que é resolvida para o objeto de registro.

Parâmetros do método retrieveRecord

Especifique a tabela, a ID do registro e as opções opcionais de consulta OData $select para moldar a resposta.

Exemplo do método retrieveRecord

Este exemplo recupera um único registro por ID e limita as colunas retornadas usando uma opção de consulta OData $select .

let record = await $pages.webAPI.retrieveRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',  '$select=name');

Método retrieveMultipleRecords

Recupera vários registros com base nas opções de consulta fornecidas.

Sintaxe: $pages.webAPI.retrieveMultipleRecords(entitySetName: string, options?: string): Promise<object>
Retorna: uma promessa que é resolvida para uma matriz de objetos de registro.

Parâmetros do método retrieveMultipleRecords

Especifique a tabela e a consulta OData opcional para filtrar os resultados e limitar as colunas retornadas.

Exemplo do método retrieveMultipleRecords

Este exemplo recupera vários registros e usa OData $select e $top para limitar a contagem de colunas e linhas retornadas.

let records = await $pages.webAPI.retrieveMultipleRecords('accounts','$select=name&$top=3');

$pages.languages

O $pages.languages objeto fornece métodos para recuperar a lista de idiomas disponíveis para o site, obter o idioma ativo no momento e definir um novo idioma ativo.

métodos $pages.languages

Use esses métodos para ler os idiomas disponíveis, verificar o idioma atual e alterá-lo para o site.

Exemplos do método $pages.languages

Esses exemplos mostram como listar todos os idiomas, ler o idioma ativo e definir um novo idioma ativo.

let allLanguages = $pages.languages.getAll();
let activeLanguage = $pages.languages.getActive();
$pages.languages.setActive('hi-IN');

$pages.agent

O objeto $pages.agent fornece métodos para estabelecer a comunicação entre o site e o agente Microsoft Copilot Studio disponível para o usuário atual.

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

Tipo de retorno: nulo – a função não retorna nada.

Objeto de resposta do agente recebido no seguinte formato:

Example

Método de retorno de chamada

Defina as responseSubscriber funções de retorno de chamada e errorSubscriber para lidar com respostas e erros do agente.

const responseSubscriber = (response) => {  
// Replace with your response handling.
console.log('Agent response:', response);
};

const errorSubscriber = (error) => {
// Replace with your error handling.
console.error('Error:', error);
};  

// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';  

Enviar mensagem ao agente

const inputActivity = {
    text: 'Hello!', // Message to the agent.
    };

$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, 
  ErrorSubscriber);

Invocar evento do cliente

const inputActivity = {
    name: 'AgentEvent', // The name of the event to be invoked
    value: {key1:'value1', key2:'value2'} // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses
    };

$pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, 
  ErrorSubscriber);

Mensagens de erro

Aqui estão possíveis mensagens de erro que os usuários podem encontrar e suas possíveis causas.