Panoramica dell'API Web dei portali

L'API Web dei portali consente un'esperienza utente più ricca all'interno delle pagine dei siti Power Pages. Puoi utilizzare l'API Web per eseguire operazioni di creazione, lettura, aggiornamento ed eliminazione in tutte le tabelle di Microsoft Dataverse dalle tue pagine Web. Ad esempio, è possibile creare un nuovo account o aggiornare un contatto senza usare un modulo o un modulo con più passaggi usando l'API Web dei portali.

L'API Web usa la /_api route ,ad esempio https://yoursite.powerappsportals.com/_api/accounts, e segue un modello RESTful simile all'API Web Dataverse.

Importante

  • L'API Web dei portali è progettata per creare un'esperienza utente più ricca nelle pagine dei portali. Non è ottimizzata per servizi di terze parti o integrazione di applicazioni. L'uso dell'API Web portals per l'integrazione con altri siti di Power Pages non è supportato.
  • Le operazioni API Web dei portali sono limitate alle tabelle relative ai dati, ad esempio, account, contatti o tabelle personalizzate. La configurazione dei metadati della tabella o dei dati della tabella di configurazione del portale, ad esempio la configurazione di tabelle del portale, ad esempio adx_contentsnippet, adx_entityform o adx_entitylist, non è supportata tramite l'API Web portals. Per un elenco completo, vedere tabelle di configurazione non supportate più avanti in questo articolo.
  • L'API web dei portali usa la cache lato server, quindi le chiamate successive all'API Web sono più veloci delle chiamate iniziali. La cancellazione della cache lato server del portale provoca un degrado temporaneo delle prestazioni.
  • Le operazioni dell'API Web dei portali richiedono una licenza per Power Pages. Ad esempio, le chiamate API Web effettuate dagli utenti anonimi contano per la capacità utente anonima. Le chiamate API Web effettuate dagli utenti autenticati (interni o esterni) non vengono conteggiate per le visualizzazioni di pagina, ma richiedono le licenze di capacità per utenti autenticati applicabili. Per altre informazioni, vedere Power Pages domande frequenti sulle licenze.
  • La chiamata di azioni e funzioni tramite l'API Web portals non è supportata.

Operazioni dell'API Web

L'API Web dei portali offre un sottoinsieme di funzionalità per le operazioni di Dataverse che puoi eseguire utilizzando l'API Dataverse. Il formato api è il più simile possibile per ridurre la curva di apprendimento.

Nota

Le operazioni dell'API Web fanno distinzione tra maiuscole e minuscole.

Operazioni dell'API Web disponibili in Power Pages

Impostazioni del sito per l'API Web

Importante

Il supporto per il valore con caratteri jolly (*) nell'impostazione del sito Webapi/<table-name>/fields è deprecato.

Sostituire * con un elenco delimitato da virgole delle colonne richieste per il tuo sito. Le richieste Web API di Power Pages per le tabelle configurate con * non riescono finché non si configurano nomi di colonna espliciti.

Per abilitare la Web API dei portali per il sito, configurare le impostazioni del sito per ogni tabella da esporre. È possibile definire le colonne disponibili per l'API Web elencandole in un'impostazione del sito, usando una vista di sistema Dataverse o combinando entrambi i metodi.

Nota

Usare la tabella nome logico per queste impostazioni, ad esempio account.

Nome dell'impostazione del sito Descrizione
Webapi/<table-name>/enabled Abilita o disabilita l'API Web per <table name>.
Impostazione predefinita:False
Valori validi:True, False
Webapi/<table-name>/fields Definisce un elenco delimitato da virgole di nomi logici di colonna disponibili tramite l'API Web. Ad esempio: name,accountnumber,telephone1. Questa impostazione è obbligatoria, a meno che Webapi/<table-name>/UseFieldsFromView non sia impostata su True e la vista di sistema configurata contenga almeno una colonna idonea. Il valore wildcard (*) è deprecato.
Webapi/<table-name>/UseFieldsFromView Se impostato su True, rende disponibili colonne da una vista di sistema Dataverse denominata Power Pages Web API Columns tramite l'API Web. Valore predefinito:False. Valori validi:True, False. Se Webapi/<table-name>/fields è configurato anche , le colonne di entrambe le origini vengono combinate.
Webapi/error/innererror Abilita o disabilita InnerError.
Impostazione predefinita:False
Valori validi:True, False

Ad esempio, per esporre l'API Web per la tabella Case in cui gli utenti autenticati possono creare, aggiornare ed eliminare record per questa entità, usare le impostazioni del sito illustrate nella tabella seguente.

Nome dell'impostazione del sito Valore dell'impostazione sito
Webapi/incident/enabled vero
Webapi/incident/fields attr1, attr2, attr3

Configurare le colonne dell'API Web usando una visualizzazione di sistema

Usando una visualizzazione di sistema, gli autori possono gestire le colonne disponibili tramite l'API Web del portale senza mantenere un elenco delimitato da virgole in un'impostazione del sito.

  1. In Power Pages studio di progettazione aprire l'area di lavoro Dati.
  2. Selezionare la tabella, selezionare la scheda Viste e quindi creare o modificare una visualizzazione di sistema pubblica.
  3. Denominare la vista Power Pages Web API Columns.
  4. Aggiungere alla visualizzazione le colonne di cui il sito ha bisogno e quindi salvare e pubblicare la vista.
  5. Nell'app Gestione portale creare l'impostazione Webapi/<table-name>/UseFieldsFromView del sito per il sito Web e impostarne il valore su True.
  6. Verifica che Webapi/<table-name>/enabled sia impostato su True.

Nota

  • Sono incluse solo le colonne della tabella primaria visualizzate nella vista. Le colonne delle tabelle correlate non sono incluse. Le colonne usate solo per il filtro o l'ordinamento non sono incluse, a meno che non vengano visualizzate anche nella visualizzazione.
  • Per le colonne di ricerca, usare la proprietà di ricerca OData corrispondente nelle richieste api Web. Il nome della proprietà usa il formato _<column-logical-name>_value. Ad esempio, la primarycontactid colonna di ricerca viene restituita come _primarycontactid_value.
  • Le modifiche apportate alla visualizzazione di sistema possono richiedere fino a cinque minuti per diventare disponibili per l'API Web.

Se entrambi Webapi/<table-name>/fields e Webapi/<table-name>/UseFieldsFromView sono configurati, l'API Web combina le colonne elencate in Webapi/<table-name>/fields con le colonne idonee della vista di sistema colonne API Web Power Pages per tale tabella.

Importante

  • L'impostazione del sito Webapi/<table-name>/UseFieldsFromView è disponibile nella versione 9.8.8.x del sito di Power Pages e successive.
  • Il supporto per il valore con caratteri jolly (*) in Webapi/<table-name>/fields è deprecato. Usare nomi di colonna espliciti, la visualizzazione di sistema Power Pages Web API Columns o entrambi.

Sicurezza con l'API Web del portale

È possibile configurare la sicurezza basata su record per i singoli record nei portali usando autorizzazioni tabella. L'API Web del portale accede ai record di tabella (entità) e rispetta le autorizzazioni della tabella concesse agli utenti tramite il ruolo Web associato.

È possibile configurare le autorizzazioni per le colonne per definire ulteriormente i privilegi per singole colonne all'interno di una tabella durante l'uso dell'API Web del portale.

Autenticazione delle richieste all'API Web del portale

Non è necessario includere un codice di autenticazione, perché la sessione dell'applicazione gestisce l'autenticazione e l'autorizzazione. Tutte le chiamate alle Web API devono includere un token CSRF (Cross-Site Request Forgery).

Utilizzo di EntitySetName

Quando si fa riferimento alle tabelle di Dataverse usando l'API Web del portale nel codice, usare EntitySetName. Per accedere alla tabella account, ad esempio, la sintassi del codice usa EntitySetName degli account; /_api/accounts().

Nota

Usa il nome logico della tabella per le impostazioni del sito (ad esempio account).

Per determinare l'EntitySetName di tabelle specifiche, seguire questi passaggi:

  1. Vai a https://make.powerapps.com

  2. Seleziona la scheda Dataverse dal pannello laterale e seleziona la tabella.

  3. Selezionare l'opzione ... (comandi) e quindi scegliere Avanzate, Strumenti e Copia nome set per copiare EntitySetName della tabella negli Appunti.

    Come individuare EntitySetName di una tabella Dataverse.

Leggi e regolamenti sulla privacy

Tutte le intestazioni di richiesta utilizzano un ID di contatto a fini di audit. Per un utente anonimo, il valore è null.

Se il log di controllo è abilitato, un utente può vedere tutti gli eventi di controllo nel log di controllo di Office 365.

Schermata del registro di controllo di Office 365.

Ulteriori informazioni:
Abilitare e utilizzare la registrazione degli impegni
Esportare, configurare e visualizzare i record del log di controllo

Tabelle di configurazione non supportate

Non è possibile usare l'API Web del portale per le tabelle di configurazione seguenti:

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

Limiti

Le tabelle di attività personalizzate ereditano colonne di base (come subject, description, activityid e createdon) dalla tabella activitypointer. Quando si configurano colonne API Web per una tabella attività personalizzata tramite Webapi/<table-name>/fields, la vista di sistema Power Pages Web API Columns o $select, includi almeno una colonna definita direttamente in tale tabella, non solo colonne ereditate.

Se si configurano solo colonne ereditate activitypointer , l'API Web non riesce a rilevare una selezione di colonna specifica della tabella. Di conseguenza, considera la richiesta come un carattere jolly (*) e restituisce l'errore seguente, anche quando si configurano in modo esplicito i campi: Attribute All Columns is not enabled for Web Api.

Raccomandazione: Includere almeno una colonna definita direttamente nella tabella attività personalizzata, ad esempio Commenti del portale/adx_portalcomment, insieme alle colonne ereditate.

Problemi noti

Gli utenti ricevono un errore CDS se richiamano una richiesta API Web GET per tabelle con più livelli di autorizzazioni di tabella uno-a-molti o molti-a-molti quando gli ambiti genitori, contatto o account aggiungono altre condizioni alla query.

Per risolvere questo problema, usare FetchXML nella query OData.

Passaggio successivo

Eseguire query sui dati tramite l'API Web dei portali

  • Ultimo aggiornamento: