Descrição geral de API Web de portais
Nota
A partir de 12 de outubro de 2022, os portais do Power Apps passam a ser Power Pages. Mais informações: O Microsoft Power Pages está agora em disponibilidade geral (blogue)
Em breve, vamos migrar e unir 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 utilizador mais rica dentro de páginas de portais do Power Apps. Pode utilizar a API Web para executar operações de criação, leitura, atualização e eliminação em todas as tabelas do Microsoft Dataverse a partir das suas páginas de portais. Por exemplo, pode criar uma nova conta, atualizar um contacto ou alterar as permissões da tabela para um produto utilizando a API Web de portais em vez da aplicação Gestão do Portal.
Nota
Também pode utilizar Web API de portais no Power Pages. Mais informações: O que é o Power Pages
Importante
- A versão do seu portal tem ser a 9.3.3.x ou posterior para que esta funcionalidade funcione.
- A API Web dos portais está construída para criar uma experiência de utilizador rica dentro das páginas do portal. Não está otimizado para serviços de terceiros ou integração de aplicações. A utilização da API Web de portais para integração com outros sites de portais do Power Apps também não é suportada.
- As operações da API Web de portais estão limitadas a tabelas relacionadas com dados, por exemplo, contas, contactos ou tabelas personalizadas. Configurar os metadados da tabela ou os dados da tabela de configuração do portal (por exemplo, configurar tabelas de portais, tais como adx_contentsnippet, adx_entityform ou adx_entitylist) não é suportado com a API Web dos portais. Para obter uma lista completa, aceda às tabelas de configuração não suportadas mais à frente neste tópico.
- A API Web de portais beneficia da colocação em cache do lado do servidor, pelo que as chamadas subsequentes para a API Web são mais rápidas do que as chamadas iniciais. Note que limpar a cache do servidor do portal causa uma degradação temporária do desempenho.
- As operações da API Web requerem uma licença dos portais do Power Apps. Por exemplo, as chamadas à API Web feitas por utilizadores anónimos são contadas para a capacidade de visualizações de páginas. As chamadas à API Web efetuadas por utilizadores autenticados (internos ou externos) não são contabilizadas para as visualizações de páginas, mas requerem licenças aplicáveis. Mais informações: FAQ de licenciamento de portais do Power Apps
Operações API Web
Os portais da API Web oferecem um subconjunto de capacidades para operações Dataverse que pode fazer utilizando a API Dataverse. Mantivemos o formato API o mais semelhante possível, de forma a reduzir a curva de aprendizagem.
Nota
As operações da API Web são sensíveis às maiúsculas e minúsculas.
Operações da API Web disponíveis em portais
- Ler registos a partir de uma tabela
- Criar um registo numa tabela
- Atualizar e eliminar registos numa tabela
- Associar e desassociar tabelas
Definições do site para a API Web
Tem de ativar a definição do site para ativar os portais API Web para o seu portal. Também poderá configurar a API Web a nível do campo que determina os campos de tabela que podem ou não ser modificados com a API Web de portais.
Nota
Utilize o nome lógico da tabela para estas definições (por exemplo, conta).
| Nome de definição do site | Description |
|---|---|
| Webapi/<table name>/enabled | Ativa ou desativa a API Web para <table name>. Predefinição: False Valores válidos: True, False |
| Webapi/<table name>/fields | Define a lista de atributos separados por vírgula que podem ser modificados com a API Web. Valores possíveis: - Todos os atributos: * - Atributos específicos: attr1,attr2,attr3 Nota: O valor deve ser um asterisco (*) ou uma lista separada por vírgulas de nomes de campo. Importante: Trata-se de uma configuração de site obrigatória. Quando esta definição faltar, verá o erro "Não há campos definidos para esta entidade." |
| Webapi/error/innererror | Ativa ou desativa o Erro Interior. Predefinição: False Valores válidos: True, False |
| Webapi/<table name>/disableodatafilter | Ativa ou desativa o filtro OData. Predefinição: False Valores válidos: True, False Consulte problemas conhecidos para obter mais informações. A definição do site está disponível na versão do portal 9.4.10.74 ou posterior. |
Nota
As definições do site devem ser definidas como Ativas para que as alterações entrem em vigor.
Por exemplo, para expor a API Web para a tabela Incidente onde os utilizadores autenticados têm permissão para executar operações de criação, atualização e eliminação nesta entidade, as definições do site são mostradas na tabela seguinte.
| Nome de definição do site | Valor de definição do site |
|---|---|
| Webapi/incident/enabled | true |
| Webapi/incident/fields | attr1, attr2, attr3 |
Segurança com os portais API Web
Pode configurar a segurança baseada em registos para registos individuais em portais utilizando permissões de tabela. A API Web dos portais acede aos registos de tabelas (entidade) e segue as permissões de tabela dadas aos utilizadores através da função Web associada.
Poderá configurar as permissões de coluna para definir ainda mais os privilégios para as colunas individuais numa tabela enquanto utiliza a API Web de portais.
Autenticação de pedidos de API Web de portais
Não é necessário incluir um código de autenticação, porque a autenticação e a autorização são geridas pela sessão da aplicação. Todas as chamadas da API Web devem incluir um token de Falsificação de pedido entre sites (CSRF).
Utilizar EntitySetName
Quando referencia as tabelas do Dataverse ao utilizar a API Web de portais no seu código, terá de utilizar EntitySetName, por exemplo, para aceder à tabela conta, a sintaxe do código utilizará EntitySetName de contas; /_api/accounts().
Nota
Utilize o nome lógico da tabela para definições do site (por exemplo, conta).
Pode determinar o EntitySetName de tabelas específicas seguindo estes passos:
Aceder ao https://make.powerapps.com
Selecione o separador Dataverse no painel lateral e selecione a tabela.
Selecione os ... (opção Comandos) e, em seguida, escolha Avançadas, Ferramentas e Copiar nome do conjunto para copiar o EntitySetName da tabela para a área de transferência.
Regulamento Geral da Proteção de Dados (GDPR)
Todos os cabeçalhos de pedido terão um ID de contacto transmitido para fins de auditoria. Para um utilizador anónimo, este será passado como null.
Se o registo de auditoria estiver ativado, um utilizador pode ver todos os eventos de auditoria no registo de auditoria Office 365.
Mais informações:
Ativar e utilizar o registo de atividades
Exportar, configurar e ver registos de registos de auditoria
Tabelas de configuração não suportadas
A API Web dos portais não pode ser utilizada 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 utilizadores receberão um erro CDS se invocarem um pedido de API Web GET para tabelas com vários níveis de 1 para muitos ou muitos para muitos permissões de tabela com o âmbito principal definido.
Para resolver este problema, a solução recomendada é utilizar FetchXML na consulta OData.
Em alternativa, estabeleça a definição de site Webapi/<table name>/disableodatafilter como True.
Importante
A alteração da definição do site Webapi/<table name>/disableodatafilter para True poderá resultar num desempenho mais lento para as chamadas GET da API Web.
A definição do site está disponível na versão do portal 9.4.10.74 ou posterior.
Próximo passo
Consultar os dados através da API Web dos portais
Consulte também
Compor pedidos HTTP e processar erros
Operações de escrita, atualização e eliminação de portais com a API Web
Tutorial: Utilizar a API Web de portais
Nota
Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)
O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).