Registros, arquivos e imagens do Dataverse da API do cliente

objeto $pages.webAPI

Use o objeto Power Pages API $pages.webAPI do Cliente para criar, recuperar, atualizar e excluir registros do Dataverse e trabalhar com o conteúdo armazenado em colunas de arquivo e imagem.

Método Descrição
createRecord Cria um novo registro na tabela especificada.
retrieveRecord Recupera um registro por seu identificador exclusivo.
retrieveMultipleRecords Recupera vários registros com base nas opções de consulta fornecidas.
updateRecord Atualiza um registro existente na tabela especificada.
deleteRecord Exclui um registro da tabela especificada.
updateSingleProperty Atualiza um único valor de coluna de um registro existente.
deleteSingleProperty Limpa o valor de uma única coluna em um registro existente definindo-o como nulo.
associateRecord Cria uma associação entre dois registros usando uma propriedade de navegação com valor de coleção.
disassociateRecord Remove uma associação entre dois registros.
getRecordCount Retorna o número total de registros na tabela especificada.
uploadFileToColumn Carrega um arquivo ou uma imagem em uma coluna de arquivo ou em uma coluna de imagem de um registro existente.
downloadFileFromColumn Baixa o conteúdo binário de uma coluna de arquivo ou de uma coluna de imagem de um registro existente.

Método createRecord

Cria um novo registro na tabela especificada.

Sintaxe: $pages.webAPI.createRecord(entitySetName: string, data: object): Promise<string>
Retorna: uma promessa que resolve para a ID do registro criado.

Parâmetros do método createRecord

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

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades. Saiba mais sobre o nome do conjunto de entidades na API Web do Dataverse
data objeto Os dados de registro a serem criados.

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.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    $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.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades. Saiba mais sobre o nome do conjunto de entidades na API Web do Dataverse.
id cadeia O identificador exclusivo do registro.
options cadeia de caracteres (opcional) Uma cadeia de caracteres de consulta OData $select opcional para limitar os dados retornados.

Note

Embora o options parâmetro seja opcional, para melhor desempenho, sempre limite o número de valores de coluna retornados usando a opção$select.

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 .

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    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 o objeto de resposta OData. A value propriedade da resposta contém a matriz de registros.

Parâmetros do método retrieveMultipleRecords

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

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
options cadeia de caracteres (opcional) Uma cadeia de caracteres de opções de consulta OData para controlar os dados retornados. Saiba mais sobre as opções de consulta OData compatíveis com a API Web do Dataverse

Note

Embora o options parâmetro seja opcional, para melhor desempenho, sempre limite o número de valores de coluna retornados usando a opção$select.

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.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let response = await $pages.webAPI.retrieveMultipleRecords('accounts', '$select=name&$top=3');
    let records = response.value;
    console.log(`Retrieved ${records.length} records.`);
});

Método updateRecord

Atualiza um registro existente na tabela especificada.

Sintaxe: $pages.webAPI.updateRecord(entitySetName: string, id: string, data: object): Promise<void>
Retorna: uma promessa que é resolvida quando o registro é atualizado.

Parâmetros do método updateRecord

Especifique a tabela, o registro a ser atualizado e os valores de coluna a serem definidos.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
id cadeia O identificador exclusivo do registro a ser atualizado.
data objeto As colunas e os valores a serem atualizados.

Exemplo do método updateRecord

Este exemplo atualiza o nome de um registro de conta.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.updateRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', { name: 'Updated Name' });
});

Método deleteRecord

Exclui um registro da tabela especificada.

Sintaxe: $pages.webAPI.deleteRecord(entitySetName: string, id: string): Promise<void>
Retorna: uma promessa que é resolvida quando o registro é excluído.

Parâmetros do método deleteRecord

Especifique a tabela e o registro a ser excluído.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
id cadeia O identificador exclusivo do registro a ser excluído.

Exemplo do método deleteRecord

Este exemplo exclui um registro de conta.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.deleteRecord('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb');
});

Método updateSingleProperty

Atualiza um único valor de coluna de um registro existente.

Sintaxe: $pages.webAPI.updateSingleProperty(entitySetName: string, id: string, property: string, value: unknown): Promise<void>
Retorna: uma promessa que é resolvida quando a coluna é atualizada.

Parâmetros do método updateSingleProperty

Especifique a tabela, o registro, a coluna a ser atualizada e o novo valor.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
id cadeia O identificador exclusivo do registro.
property cadeia O nome da coluna a ser atualizada.
value desconhecido O novo valor da coluna.

Exemplo do método updateSingleProperty

Este exemplo atualiza a coluna de nome de um registro de conta.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.updateSingleProperty('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'name', 'New Name');
});

Método deleteSingleProperty

Limpa o valor de uma única coluna em um registro existente definindo-o como nulo.

Sintaxe: $pages.webAPI.deleteSingleProperty(entitySetName: string, id: string, property: string): Promise<void>
Retorna: uma promessa que é resolvida quando o valor da coluna é limpo.

Parâmetros do método deleteSingleProperty

Especifique a tabela, o registro e a coluna a serem desmarcadas.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
id cadeia O identificador exclusivo do registro.
property cadeia O nome da coluna a ser desmarcada.

Exemplo do método deleteSingleProperty

Este exemplo limpa a coluna de descrição de um registro de conta.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.deleteSingleProperty('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'description');
});

Método associateRecord

Cria uma associação entre dois registros usando uma propriedade de navegação com valor de coleção. Esse método usa a operação OData $ref para criar o link.

Sintaxe: $pages.webAPI.associateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Retorna: uma promessa que é resolvida quando os registros são associados.

Parâmetros do método associateRecord

Especifique primeiro o registro pai e, em seguida, a propriedade de navegação e o registro relacionado.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades do registro pai em um lado da relação.
id cadeia O identificador exclusivo do registro pai.
navigationProperty cadeia O nome da propriedade de navegação com valor de coleção que define a relação.
relatedEntitySetName cadeia O nome do conjunto de entidades do registro relacionado em muitos lados da relação.
relatedId cadeia O identificador exclusivo do registro relacionado a ser associado.

Important

Sempre especifique o registro pai em um lado da relação primeiro, usando os parâmetros e id os entitySetName parâmetros.

Exemplo do método associateRecord

Este exemplo associa um registro de contato a um registro de conta usando a contact_association propriedade de navegação.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.associateRecord(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'contact_association',
        'contacts',
        'cccccccc-0000-1111-2222-dddddddddddd'
    );
});

método disassociateRecord

Remove uma associação entre dois registros.

Sintaxe: $pages.webAPI.disassociateRecord(entitySetName: string, id: string, navigationProperty: string, relatedEntitySetName: string, relatedId: string): Promise<void>
Retorna: uma promessa que é resolvida quando a associação é removida.

parâmetros do método disassociateRecord

Especifique primeiro o registro pai e, em seguida, a propriedade de navegação e o registro relacionado.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades do registro pai em um lado da relação.
id cadeia O identificador exclusivo do registro pai.
navigationProperty cadeia O nome da propriedade de navegação com valor de coleção que define a relação.
relatedEntitySetName cadeia O nome do conjunto de entidades do registro relacionado.
relatedId cadeia O identificador exclusivo do registro relacionado a ser desassociado.

Important

Sempre especifique o registro pai em um lado da relação primeiro, usando os parâmetros e id os entitySetName parâmetros.

exemplo do método disassociateRecord

Este exemplo remove a associação entre um registro de conta e um registro de contato.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.webAPI.disassociateRecord(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'contact_association',
        'contacts',
        'cccccccc-0000-1111-2222-dddddddddddd'
    );
});

Método getRecordCount

Retorna o número total de registros na tabela especificada. Esse método chama o ponto de extremidade OData /$count , que retorna um inteiro em vez de uma coleção de registros.

Sintaxe: $pages.webAPI.getRecordCount(entitySetName: string): Promise<number>
Retorna: uma promessa que é resolvida para o número de registros.

Parâmetros do método getRecordCount

Especifique a tabela na qual contar registros.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.

Note

O servidor retorna uma contagem máxima de 5.000. Quando uma tabela contém mais de 5.000 registros, o resultado é 5.000. Para recuperar registros junto com sua contagem total, use o método retrieveMultipleRecords com a opção$count=true de consulta. Esse método retorna a coleção na value propriedade da resposta e a contagem total na @odata.count propriedade.

Exemplo do método getRecordCount

Este exemplo retorna o número total de registros de conta.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const total = await $pages.webAPI.getRecordCount('accounts');
    console.log(`Total accounts: ${total}`);
});

Método uploadFileToColumn

Carrega um arquivo ou uma imagem em uma coluna de arquivo ou em uma coluna de imagem de um registro existente. O Dataverse armazena o conteúdo binário e atualiza automaticamente a {columnName}_Name coluna com o nome do arquivo.

Sintaxe: $pages.webAPI.uploadFileToColumn(entitySetName: string, id: string, columnName: string, file: File): Promise<void>
Retorna: uma promessa que é resolvida quando o arquivo é carregado.

Parâmetros do método uploadFileToColumn

Especifique a tabela, o registro, a coluna e o arquivo a ser carregado.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
id cadeia O identificador exclusivo do registro.
columnName cadeia O nome lógico da coluna de arquivo ou imagem.
file Arquivo O arquivo a ser carregado.

Note

Você pode usar esse método com colunas de imagem. O Dataverse remove metadados EXIF no servidor e gera uma miniatura automaticamente. Use o método downloadFileFromColumn para baixar a imagem completa ou a miniatura.

Exemplo do método uploadFileToColumn

Este exemplo carrega um arquivo selecionado por alguém usando um elemento de entrada de arquivo.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const fileInput = document.querySelector('input[type="file"]');

    if (!fileInput || fileInput.files.length === 0) {
        return;
    }

    const file = fileInput.files[0];
    await $pages.webAPI.uploadFileToColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'new_attachment', file);
});

Método downloadFileFromColumn

Baixa o conteúdo binário de uma coluna de arquivo ou de uma coluna de imagem de um registro existente. Arquivos grandes são baixados em partes de 4 MB e combinados em um único Blob automaticamente.

Sintaxe: $pages.webAPI.downloadFileFromColumn(entitySetName: string, id: string, columnName: string, options?: object): Promise<Blob>
Retorna: uma promessa que é resolvida para um Blob que contém os dados binários. A type propriedade do Blob contém o tipo MIME que o servidor retorna.

Parâmetros do método downloadFileFromColumn

Especifique a tabela, o registro e a coluna da qual baixar.

Parâmetro Tipo Descrição
entitySetName cadeia O nome do conjunto de entidades.
id cadeia O identificador exclusivo do registro.
columnName cadeia O nome lógico da coluna de arquivo ou imagem.
options objeto (opcional) Opções para o download. A size propriedade se aplica a colunas de imagem e aceita full baixar a imagem original ou thumbnail baixar a miniatura gerada pelo Dataverse. O valor padrão é full.

Note

A resposta não inclui o nome do arquivo. Para obter o nome do arquivo, use o método retrieveRecord para consultar a {columnName}_Name coluna do registro.

exemplos do método downloadFileFromColumn

Este exemplo baixa um arquivo de uma coluna de arquivo e solicita que o navegador o salve.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const blob = await $pages.webAPI.downloadFileFromColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'new_attachment');

    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'downloaded_file';
    a.click();
    URL.revokeObjectURL(url);
});

Este exemplo baixa a imagem completa e a miniatura de uma coluna de imagem.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    // Full-resolution image, which is the default.
    const fullBlob = await $pages.webAPI.downloadFileFromColumn('accounts', 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 'entityimage');

    // Thumbnail that Dataverse generates.
    const thumbnailBlob = await $pages.webAPI.downloadFileFromColumn(
        'accounts',
        'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
        'entityimage',
        { size: 'thumbnail' }
    );
});
  • Última atualização em