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
- Leia os registros de uma tabela
- Criar um registro em uma tabela
- Atualizar e excluir registros em uma tabela
- Associar e desassociar tabelas
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.
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:
Acessar o https://make.powerapps.com
Selecione a guia Dataverse no painel lateral e selecione a tabela.
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.
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.
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).