Visão geral da API Web de portais

A API Web de portais permite uma experiência de usuário mais avançada em sites do Power Pages. Você pode usar a API da Web para executar operações de criação, leitura, atualização e exclusão em todas as tabelas do Microsoft Dataverse em suas páginas da Web. Por exemplo, você pode criar uma nova conta ou atualizar um contato sem usar um formulário ou formulário de várias etapas usando a API Web dos portais.

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

Importante

  • 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 ao uso da API Web de portais para integração com outros sites do Power Pages.
  • As operações da API Web do Portals limitam-se a tabelas relacionadas a dados, por exemplo, contas, contatos ou às suas tabelas personalizadas. A configuração de metadados de tabela ou dados da tabela de configuração do portal, por exemplo, a configuração de tabelas de portais, como adx_contentsnippet, adx_entityform ou adx_entitylist, não é compatível com o uso da API Web de portais. Para obter uma lista completa, consulte tabelas de configuração sem suporte posteriormente neste artigo.
  • A API Web dos portais se beneficia de cache no lado do servidor, portanto as chamadas subsequentes para a API Web são mais rápidas do que as chamadas iniciais. 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 do Power Pages. Por exemplo, as chamadas à API Web feitas por usuários anônimos contam para a capacidade de usuários anônimos. As chamadas à API Web feitas por usuários autenticados (internos ou externos) não contam como exibições de página, mas exigem licenças de capacidade aplicáveis para usuário autenticado. Para obter mais informações, consulte Perguntas frequentes sobre licenciamento do Power Pages.
  • Não há suporte para chamar ações e funções usando a API Web dos portais.

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. O formato de 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 no Power Pages

Configurações do site para a API Web

Importante

O suporte para o valor curinga (*) na configuração do Webapi/<table-name>/fields site foi preterido.

Substitua * por uma lista separada por vírgulas das colunas exigidas pelo seu site. As solicitações da API Web do Power Pages para tabelas configuradas com * falham até que você configure nomes de coluna explícitos.

Para habilitar a API Web de portais para seu site, defina as configurações do site para cada tabela que você deseja expor. Você pode definir as colunas disponíveis para a API Web listando-as em uma configuração de site, usando uma exibição do sistema dataverse ou combinando ambos os métodos.

Observação

Use o nome lógico da tabela para essas configurações (por exemplo, conta).

Nome da configuração do site Descrição
Webapi/<table-name>/enabled Habilita ou desabilita a API Web para <table name>.
Padrão:False
Valores válidos:True, False
Webapi/<table-name>/fields Define uma lista separada por vírgulas de nomes lógicos de coluna disponíveis por meio da API Web. Por exemplo, name,accountnumber,telephone1. Essa configuração é necessária, a menos que True esteja definido como Webapi/<table-name>/UseFieldsFromView e a exibição do sistema configurada contenha pelo menos uma coluna qualificada. O valor curinga (*) está obsoleto.
Webapi/<table-name>/UseFieldsFromView Quando definido como True, disponibiliza colunas de uma exibição do sistema Dataverse chamada Power Pages Web API Columns por meio da API Web. Padrão:False. Valores válidos:True, False. Se Webapi/<table-name>/fields também estiver configurado, as colunas de ambas as fontes serão combinadas.
Webapi/error/innererror Habilita ou desabilita InnerError.
Padrão:False
Valores válidos:True, False

Por exemplo, para expor a API Web da tabela Case em que os usuários autenticados podem criar, atualizar e excluir registros dessa entidade, use as configurações de site mostradas na tabela a seguir.

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

Configurar colunas de API Web usando uma exibição do sistema

Usando uma exibição do sistema, os autores podem gerenciar as colunas disponíveis por meio da API Web do portal sem manter uma lista separada por vírgulas em uma configuração de site.

  1. No estúdio de design do Power Pages, abra o workspace de dados.
  2. Selecione a tabela, selecione a guia Modos de exibição e, em seguida, crie ou edite um modo de exibição de sistema público.
  3. Nomeie o modo de exibição Power Pages Web API Columns.
  4. Adicione as colunas que seu site precisa para o modo de exibição e salve e publique o modo de exibição.
  5. No aplicativo Gerenciamento de Portal, crie a configuração de site Webapi/<table-name>/UseFieldsFromView para o site e defina seu valor como True.
  6. Confirme se Webapi/<table-name>/enabled está definido como True.

Observação

  • Somente as colunas da tabela primária exibidas na exibição são incluídas. Colunas de tabelas relacionadas não estão incluídas. As colunas usadas somente para filtragem ou classificação não são incluídas, a menos que também sejam exibidas na exibição.
  • Para colunas de pesquisa, use a propriedade de pesquisa OData correspondente em solicitações de API Web. O nome da propriedade usa o formato _<column-logical-name>_value. Por exemplo, a primarycontactid coluna de pesquisa é retornada como _primarycontactid_value.
  • As alterações na exibição do sistema podem levar até cinco minutos para ficarem disponíveis para a API Web.

Se ambos Webapi/<table-name>/fields e Webapi/<table-name>/UseFieldsFromView estiverem configurados, a API Web combinará as colunas listadas em Webapi/<table-name>/fields com colunas elegíveis do modo de exibição do sistema Power Pages Colunas da API Web para essa tabela.

Importante

  • A configuração de site Webapi/<table-name>/UseFieldsFromView está disponível na versão 9.8.8.x e posteriores do site do Power Pages.
  • O suporte para o valor curinga (*) em Webapi/<table-name>/fields está preterido. Use nomes de coluna explícitos, o modo de exibição do sistema Power Pages Web API Columns ou ambos.

Segurança com a API Web do portal

Você pode configurar a segurança baseada em registro para registros individuais em portais usando permissões de tabela. A API Web do portal acessa registros de tabela (entidade) e segue as permissões de tabela fornecidas aos usuários por meio da função da 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 do portal.

Autenticando solicitações de API Web do portal

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

Uso de EntitySetName

Ao fazer referência a tabelas do Dataverse usando a API Web do portal em seu código, use o EntitySetName. Para acessar a tabela da conta , por exemplo, a sintaxe de código usa o EntitySetName de contas; /_api/accounts().

Observação

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

Para determinar o EntitySetName de tabelas específicas, siga estas etapas:

  1. Vá para https://make.powerapps.com

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

  3. Selecione ... (opção Comandos) e, em seguida, escolha Advanced, Tools e Copy set name para copiar o EntitySetName da tabela para sua área de transferência.

    Como localizar EntitySetName de uma tabela do Dataverse.

Leis e regulamentos de privacidade

Todos os cabeçalhos de solicitação usam uma ID de contato para fins de auditoria. Para um usuário anônimo, o valor é 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.

Captura de tela do log de auditoria do Office 365.

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

Você 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, createdon e activityid) da tabela activitypointer. Quando você configura colunas de API Web para uma tabela de atividade personalizada usando Webapi/<table-name>/fields, a exibição do sistema Power Pages Colunas da API Web ou $select, inclua pelo menos uma coluna definida diretamente nessa tabela, não apenas colunas herdadas.

Se você configurar apenas colunas herdadas activitypointer , a API Web não poderá detectar uma seleção de coluna específica da tabela. Como resultado, ele trata a solicitação como um curinga (*) e retorna o seguinte erro, mesmo quando você configura explicitamente os campos: Attribute All Columns não está habilitado para a API Web.

Recomendação: Inclua pelo menos uma coluna definida diretamente na tabela de atividades personalizadas, como /adx_portalcomment, juntamente com quaisquer colunas herdadas.

Problemas conhecidos

Os usuários receberão um erro de CDS se invocarem uma GET solicitação de API Web para tabelas que têm vários níveis de permissões de tabela de um-para-muitos ou muitos-para-muitos quando os escopos parentais, de contato ou de conta adicionam mais condições à consulta.

Para resolver esse problema, use FetchXML na consulta OData.

Próxima etapa

Consultar dados usando portais API Web

  • Última atualização em