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, atualizar um contacto sem utilizar um formulário ou formulário com vários passos utilizando a API Web de portais.
Importante
- A versão do seu site do Power Pages tem ser a 9.3.3.x ou posterior para que esta caraterística 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 sites do Power Pages 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 de portais requerem uma licença do Power Pages. Por exemplo, as chamadas à API Web feitas por utilizadores anónimos são contadas para a capacidade de utilizadores anónimos. 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 de capacidade de utilizadores autenticados aplicáveis. Mais informações: FAQ sobre licenciamento do Power Pages
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 no Power Pages
- 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/<nome da tabela>/enabled | Ativa ou desativa a API Web para <nome da tabela>. Predefinido: False Valores válidos: True False |
| Webapi/<nome da tabela>/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. Predefinido: False Valores válidos: True False |
| Webapi/<nome da tabela>/disableodatafilter | Ativa ou desativa o filtro OData. Predefinido: 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.
Leis e regulamentações de privacidade
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 obterão um erro de CDS se invocarem um pedido de API Web GET para tabelas com vários níveis de permissões de tabela de 1 para muitos ou muitos para muitos quando os âmbitos Parental, Contacto ou Conta adicionam condições adicionais à consulta.
Para resolver esse problema, a solução recomendada é usar FetchXML na consulta OData.
Em alternativa, estabeleça a definição de site Webapi/<nome da tabela>/disableodatafilter como True.
Importante
A alteração da definição do site Webapi/<nome da tabela>/disableodatafilter como 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