Descrição geral de API Web de portais

A API Web de portais permite uma experiência de utilizador mais rica dentro de sites do Power Pages. Pode utilizar a API Web para efetuar operações de criação, leitura, atualização e eliminação entre todas as tabelas do Microsoft Dataverse a partir das suas páginas Web. Por exemplo, pode criar uma nova conta ou atualizar um contacto sem usar um formulário ou formulário multipasso , utilizando a Web API do portal.

A Web API utiliza a /_api rota (por exemplo, https://yoursite.powerappsportals.com/_api/accounts) e segue um padrão RESTful semelhante ao da Web API do Dataverse.

Importante

  • 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. Usar a API Web do portal para integrar com outros sites do Power Pages não é suportado.
  • As operações da API Web de portais estão limitadas a tabelas relacionadas com dados, por exemplo, contas, contactos ou tabelas personalizadas. A configuração de metadados de tabelas 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 é suportada pela utilização da Web API do portal. Para uma lista completa, consulte tabelas de configuração não suportadas mais adiante neste artigo.
  • 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. Limpar a cache do servidor do portal causa uma degradação temporária do desempenho.
  • As operações da API Web de portais requerem uma licença do Power Pages. Por exemplo, as chamadas Web API feitas por utilizadores anónimos contam para a capacidade dos utilizadores anónimos. As chamadas de API web feitas por utilizadores autenticados (internos ou externos) não contam para visualizações de página, mas requerem licenças de capacidade de utilizador autenticadas aplicáveis. Para mais informações, consulte as Perguntas Frequentes sobre licenciamento do Power Pages.
  • Chamar ações e funções através da API Web do portal não é suportado.

Operações API Web

A API Web dos portais oferece um subconjunto de funcionalidades para as operações do Dataverse que pode efetuar através da API do Dataverse. O formato da API é o mais semelhante possível para 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 no Power Pages

Definições do site para a API Web

Importante

O suporte ao valor coringa (*) na Webapi/<table-name>/fields definição do site está obsoleto.

Substitua * por uma lista separada por vírgulas das colunas exigidas pelo seu site. Os pedidos da API Web do Power Pages para tabelas configuradas com * falham até configurares nomes explícitos de colunas.

Para ativar a API Web do portal para o seu site, configure as definições do site para cada tabela que pretende expor. Pode definir as colunas disponíveis para a Web API, listando-as numa configuração do site, usando uma vista do sistema Dataverse ou combinando ambos os métodos.

Nota

Utilize o nome lógico da tabela para estas definições (por exemplo, conta).

Nome da configuração do site Descrição
Webapi/<table-name>/enabled Ativa ou desativa a API Web para <nome da tabela>.
Predefinição:False
Valores válidos:True, False
Webapi/<table-name>/fields Define uma lista separada por vírgulas de nomes lógicos de colunas disponíveis através da Web API. Por exemplo, name,accountnumber,telephone1. Esta configuração é obrigatória, a menos que Webapi/<table-name>/UseFieldsFromView esteja definida para True e a vista do sistema configurada contenha pelo menos uma coluna elegível. O valor do coringa (*) está obsoleto.
Webapi/<table-name>/UseFieldsFromView Quando definido para True, torna disponíveis através da Web API as colunas de uma vista do sistema Dataverse chamada Power Pages Web API Columns. Padrão:False. Valores válidos:True, False. Se Webapi/<table-name>/fields também estiver configurado, as colunas de ambas as fontes são combinadas.
Webapi/error/innererror Ativa ou desativa InnerError.
Predefinição:False
Valores válidos:True, False

Por exemplo, para expor a Web API da tabela de Casos onde utilizadores autenticados podem criar, atualizar e eliminar registos para esta entidade, utilize as definições do site apresentadas na tabela seguinte.

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

Configure as colunas da Web API usando uma vista do sistema

Ao utilizar uma vista de sistema, os criadores podem gerir as colunas disponíveis através da Web API do portal sem manter uma lista separada por vírgulas numa definição do site.

  1. No Power Pages Design Studio, abra o espaço de trabalho de Dados.
  2. Selecione a tabela, selecione o separador Vistas e depois crie ou edite uma vista pública do sistema.
  3. Nomeie a vista Power Pages Web API Columns.
  4. Adicione as colunas que o seu site precisa à visualização e depois guarde e publique a visualização.
  5. Na aplicação Portal Management, crie a Webapi/<table-name>/UseFieldsFromView definição do site para o site e defina o seu valor para True.
  6. Confirme se Webapi/<table-name>/enabled está definido como True.

Nota

  • Apenas as colunas da tabela primária que são apresentadas na vista estão incluídas. Colunas de tabelas relacionadas não estão incluídas. Colunas usadas apenas para filtragem ou ordenação não estão incluídas, a menos que também sejam exibidas na vista.
  • Para colunas de lookup, use a propriedade de lookup do OData correspondente nos pedidos da API Web. O nome da propriedade utiliza o formato _<column-logical-name>_value. Por exemplo, a primarycontactid coluna de consulta é devolvida como _primarycontactid_value.
  • As alterações à visualização do sistema podem demorar até cinco minutos a ficar disponíveis para a Web API.

Se ambos Webapi/<table-name>/fields e Webapi/<table-name>/UseFieldsFromView estiverem configurados, a Web API combina as colunas listadas em Webapi/<table-name>/fields com colunas elegíveis da vista de sistema Power Pages Web API Columns para essa tabela.

Importante

  • A definição do site Webapi/<table-name>/UseFieldsFromView está disponível na versão 9.8.8.x do site do Power Pages e em versões posteriores.
  • O suporte ao valor curinga (*) em Webapi/<table-name>/fields está obsoleto. Utilize nomes explícitos de colunas, a vista do sistema Power Pages Web API Columns, ou ambos.

Segurança com a API Web do portal

Pode configurar a segurança baseada em registos para registos individuais em portais usando permissões de tabelas. A API Web do portal acede aos registos de tabelas (entidades) e segue as permissões de tabela concedidas aos utilizadores através da função Web associada.

Pode configurar permissões de coluna para definir ainda mais privilégios para colunas individuais dentro de uma tabela enquanto utiliza a Web API do portal.

Autenticar pedidos da Web API do portal

Não é necessário incluir um código de autenticação porque a sessão da aplicação gere a autenticação e a autorização. Todas as chamadas à API da Web devem incluir um token de Cross-Site Request Forgery (CSRF).

Utilizar EntitySetName

Ao referir-se às tabelas do Dataverse usando a API Web do portal no seu código, use o EntitySetName. Para aceder à tabela de contas , por exemplo, a sintaxe do código usa o EntitySetName das contas; /_api/accounts().

Nota

Utilize o nome lógico da tabela para definições do site (por exemplo, conta).

Para determinar o EntitySetName de tabelas específicas, siga estes passos:

  1. Aceder ao https://make.powerapps.com

  2. Selecione o separador Dataverse no painel lateral e selecione a tabela.

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

    Como localizar EntitySetName de uma tabela do Dataverse.

Leis e regulamentações de privacidade

Todos os cabeçalhos de pedidos utilizam um ID de contacto para fins de auditoria. Para um utilizador anónimo, o valor é null.

Se o registo de auditoria estiver ativado, um utilizador pode ver todos os eventos de auditoria no registo de auditoria Office 365.

Captura de ecrã do registo de auditoria do Office 365.

Mais informações:
Ativar e utilizar o registo de atividades
Exportar, configurar e visualizar registos de auditoria

Tabelas de configuração não suportadas

Não pode usar a API Web do Portal 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

Limitations

Tabelas de atividades personalizadas herdam colunas base (como subject, description, activityid, e createdon) da activitypointer tabela. Quando configura colunas Web API para uma tabela de atividades personalizada usando Webapi/<table-name>/fields, a vista do sistema Power Pages Web API Columns, ou $select, inclui pelo menos uma coluna definida diretamente nessa tabela, não apenas colunas herdadas.

Se configurar apenas colunas herdadas activitypointer , a Web API não consegue detetar uma seleção de colunas específica de tabela. Como resultado, trata o pedido como um caráter universal (*) e devolve o seguinte erro, mesmo quando configura explicitamente os campos: O atributo All Columns não está ativado para Web Api.

Recomendação: Inclua pelo menos uma coluna definida diretamente na tabela de atividades personalizada, como Comentários do Portal/adx_portalcomment, juntamente com quaisquer colunas herdadas.

Problemas conhecidos

Os utilizadores recebem um erro CDS se invocarem um GET pedido da Web API para tabelas que têm múltiplos níveis de permissões de tabela um-para-muitos ou muitos-para-muitos, quando os escopos Parental, Contacto ou Conta adicionam mais condições à consulta.

Para resolver este problema, use FetchXML na consulta OData.

Próximo passo

Consultar os dados através da API Web dos portais

  • Última atualização a