Compartilhar via


Visão geral da API Web de portais

Observação

Desde o dia 12 de outubro de 2022, os portais do Power Apps passaram a ser Power Pages. Mais Informações: O Microsoft Power Pages já está disponível para todos (blog)
Em breve, migraremos e mesclaremos a documentação dos portais do Power Apps com a documentação do Power Pages.

A API Web dos portais permite uma experiência de usuário mais rica dentro de páginas dos portais do Power Apps. Você pode usar a API Web para executar operações criar, ler, atualizar e excluir em todas as tabelas do Microsoft Dataverse de suas páginas de portais. Por exemplo, é possível criar uma conta, atualizar um contato ou alterar as permissões da tabela referente a um produto usando a API Web de portais em vez do aplicativo de Gerenciamento do Portal.

Observação

Você também pode usar API Web de portais no Power Pages. Mais informações: O que é o Power Pages

Importante

  • Sua versão do portal deve ser 9.3.3.x ou posterior para que este recurso funcione.
  • A API Web de portais foi desenvolvida para criar uma experiência de usuário rica em páginas de portais. Ela não foi otimizada para integração com serviços ou aplicativos de terceiros. Não há suporte para a utilização da API Web dos portais para integração com outros sites de portais do Power Apps.
  • As operações de API Web estão limitadas a tabelas relacionadas aos dados—por exemplo, contas, contatos ou suas tabelas personalizadas. Configurar metadados da tabela ou dados da tabela de configuração do portal—por exemplo, configurar tabelas de portais, como adx_contentsnippet, adx_entityform, ou adx_entitylist—não é compatível com a API Web de portais. Para obter uma lista completa, acesse as tabelas de configuração não compatíveis, mais adiante neste tópico.
  • Os portais da API Web se beneficiam de cache do servidor, tornando as chamadas subsequentes para a API Web mais rápidas do que as chamadas iniciais. Observe que limpar o cache do servidor do portal causa degradação temporária do desempenho.
  • As operações da API Web de Portals exigem uma licença de portais do Power Apps. Por exemplo, chamadas de API da Web feitas por usuários anônimos são contadas para a capacidade de exibição de página. As chamadas de API da Web feitas por usuários autenticados (internos ou externos) não são contadas para visualizações de página, mas requerem licenças aplicáveis. Mais informações: Perguntas frequentes sobre licenciamento dos portais do Power Apps

Operações da API Web

A API Web de portais oferece um subconjunto de recursos para operações do Dataverse que você pode executar usando a API Dataverse. Mantivemos o formato da API o mais semelhante possível para reduzir a curva de aprendizado.

Observação

As operações da API Web diferenciam maiúsculas de minúsculas.

Operações da API Web disponíveis em portais

Observação

Não há suporte a chamadas de ações e funções usando da API Web dos portais.

Configurações do site para a API Web

É necessário habilitar a configuração do site para habilitar a API Web de portais para o seu portal. Você também pode configurar a API Web em nível de campo que determina os campos da tabela que podem ou não ser modificados com a API Web de portais.

Observação

Usar a tabela nome lógico para essas configurações (por exemplo conta).

Nome da configuração do site Description
Webapi/<table name>/enabled Habilita ou desabilita API Web para <table name>.
Padrão: False
Valores válidos: True, False
Webapi/<table name>/fields Define a lista de atributos separados por vírgulas que podem ser modificados com a API Web.
Valores possíveis:
- Todos os atributos: *
- Atributos específicos: attr1,attr2,attr3
Observação: o valor deve ser um asterisco (*) ou uma lista de nomes de campos separados por vírgulas.
Importante: esta é uma configuração de site obrigatória. Quando esta configuração estiver faltando, você verá o erro "Nenhum campo definido para esta entidade".
Webapi/error/innererror Habilita ou desabilita InnerError.
Padrão: False
Valores válidos: True, False
Webapi/<table name>/disableodatafilter Habilita ou desabilita o filtro OData.
Padrão: False
Valores válidos: True, False Consulte Problemas conhecidos para obter mais informações. A configuração do site está disponível na versão do portal 9.4.10.74 ou posterior.

Observação

As configurações do site devem ser definidas como Ativas para que as alterações entrem em vigor.

Por exemplo, para expor a API Web da tabela de Casos em que usuários autenticados podem executar operações de criação, atualização e exclusão nesta entidade, as configurações do site são exibidas na seguinte tabela.

Nome da configuração do site Valor de configuração do site
Webapi/incident/enabled true
Webapi/incident/fields attr1, attr2, attr3

Segurança com a API Web de portais

É possível configurar a segurança baseada em registros para registros individuais em portais usando as permissões de tabela. A API Web de portais acessa registros da tabela (entidade) e segue as permissões da tabela fornecidas a usuários por meio da função Web associada.

Você pode configurar permissões de coluna para definir ainda mais privilégios para colunas individuais em uma tabela ao usar a API Web dos portais.

Segurança da API Web de portais.

Autenticação de solicitações da API Web de portais

Você não precisa incluir um código de autenticação porque a autenticação e a autorização são gerenciadas pela sessão do aplicativo. Todas as chamadas da API Web devem incluir um token de solicitação intersite forjada (CSRF).

Uso de EntitySetName

Ao se referir a tabelas do Dataverse que usam a API Web de portais em seu código, você precisa usar o EntitySetName, por exemplo, para acessar o tabela conta, a sintaxe do código usará o EntitySetName de contas; /_api/accounts().

Observação

Usar a tabela nome lógico para configurações do site (por exemplo conta).

Você pode determinar EntitySetName de tabelas específicas seguindo estas etapas:

  1. Acessar o https://make.powerapps.com

  2. Selecione a guia Dataverse no painel lateral e selecione a tabela.

  3. Selecione ... (opção Comandos) e escolha Avançado, Ferramentas e Copiar nome do conjunto para copiar EntitySetName da tabela para a área de transferência.

    Como localizar EntitySetName de uma tabela do Dataverse.

Regulamento Geral sobre a Proteção de Dados (GDPR)

Todos os cabeçalhos de solicitação terão uma ID de contato passada para fins de auditoria. Para um usuário anônimo, isso será transmitido como null.

Se o registro em log de auditoria estiver habilitado, o usuário poderá ver todos os eventos de auditoria no log de auditoria do Office 365.

Log de auditoria do Office 365.

Para obter mais informações:
Habilitar e usar o log de atividades
Exportar, configurar e exibir registros do log de auditoria

Tabelas de configuração não compatíveis

A API Web de portais não pode ser usada para as seguintes tabelas de configuração:

adx_contentaccesslevel

adx_contentsnippet

adx_entityform

adx_entityformmetadata

adx_entitylist

adx_entitypermission

adx_entitypermission_webrole

adx_externalidentity

adx_pagealert

adx_pagenotification

adx_pagetag

adx_pagetag_webpage

adx_pagetemplate

adx_portallanguage

adx_publishingstate

adx_publishingstatetransitionrule

adx_publishingstatetransitionrule_webrole

adx_redirect

adx_setting

adx_shortcut

adx_sitemarker

adx_sitesetting

adx_urlhistory

adx_webfile

adx_webfilelog

adx_webform

adx_webformmetadata

adx_webformsession

adx_webformstep

adx_weblink

adx_weblinkset

adx_webnotificationentity

adx_webnotificationurl

adx_webpage

adx_webpage_tag

adx_webpageaccesscontrolrule

adx_webpageaccesscontrolrule_webrole

adx_webpagehistory

adx_webpagelog

adx_webrole_systemuser

adx_website

adx_website_list

adx_website_sponsor

adx_websiteaccess

adx_websiteaccess_webrole

adx_websitebinding

adx_websitelanguage

adx_webtemplate

Problemas conhecidos

Os usuários receberão um erro de CDS se invocarem uma solicitação GET da API Web para tabelas com vários níveis de permissões de tabela 1 para muitos ou muitos para muitos com o escopo pai definido.

Para resolver esse problema, a solução recomendada é usar FetchXML na consulta OData.

Como alternativa, defina a configuração do site Webapi/<table name>/disableodatafilter como True.

Importante

Alterar a configuração do site Webapi/<table name>/disableodatafilter para True pode resultar em desempenho mais lento para chamadas GET da API Web.

A configuração do site está disponível na versão do portal 9.4.10.74 ou posterior.

Próxima etapa

Consultar dados usando portais API Web

Confira também

Compor solicitações HTTP e tratar erros
Operações de gravação, atualização e exclusão de portais usando a API Web
Tutorial: usar a API Web do portal

Observação

Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)

A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).