Query di dati utilizzando l'API Web dei portali

Articolo
03/16/2023

Nota

A partire dal 12 ottobre 2022, i portali Power Apps sono denominati Power Pages. Altre informazioni: Microsoft Power Pages è ora generalmente disponibile (blog)
A breve verrà eseguita la migrazione e l'unione della documentazione dei portali Power Apps con la documentazione di Power Pages.

Puoi usare le operazioni API Web disponibili nei portali. Le operazioni API Web sono costituite da richieste e risposte HTTP. Questo articolo fornisce operazioni di lettura di esempio, metodi, URI e JSON di esempio che puoi usare nella richiesta HTTP.

Prerequisiti

La versione del tuo portale deve essere 9.4.1.x o successiva.
Abilita la tabella e il campo per le operazioni dell'API Web. Maggiori informazioni: Impostazioni del sito per l'API Web
L'API Web dei portali accede ai record della tabella e segue le autorizzazioni della tabella fornite agli utenti tramite i ruoli web associati. Assicurati di configurare le autorizzazioni della tabella corrette. Più informazioni: Creare ruoli web

Nota

Quando si fa riferimento alle tabelle Dataverse utilizzando l'API Web dei portali, è necessario utilizzare EntitySetName, ad esempio, per accedere alla tabella degli account, la sintassi del codice utilizzerà EntitySetName di account.

Query di record

L'esempio seguente esegue una query dei record dell'account:

Operazione	Method	URI
Recupera record di tabella	GET	`[Portal URI]/_api/accounts` Esempio: `https://contoso.powerappsportals.com/_api/accounts`

Risposta di esempio

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

Usa le opzioni di query di sistema $select e $top per restituire la proprietà nome per i primi tre account:

Operazione	Method	URI
Recupera i primi tre record di entità	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Recupera l'account utilizzando l'ID account:

Operazione	Method	URI
Recupera una proprietà specifica per un record	GET	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Esempio: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Risposta di esempio

{
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}

Applicare le opzioni di query di sistema

Ciascuna delle opzioni di query di sistema che aggiungi all'URL per il set di entità viene aggiunta utilizzando la sintassi per le stringhe di query. La prima è aggiunta dopo [?] e le seguenti opzioni di query sono separate usando [&]. Tutte le opzioni di query fanno distinzione tra maiuscole e minuscole, come mostrato nell'esempio seguente:

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3`

Richiedere proprietà specifiche

Utilizza l'opzione di query di sistema $select per limitare le proprietà restituite come mostrato nell'esempio seguente:

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Importante

Questa è una procedura consigliata per le prestazioni. Se le proprietà non sono specificate e hai configurato il valore di impostazione del sito Webapi/<table name>/fields su *, tutte le proprietà verranno restituite utilizzando $select. Se non vengono specificate proprietà, verrà restituito un errore.

Filtrare i risultati

Utilizza l'opzione di query di sistema $filter per impostare i criteri secondo cui verranno restituite le righe.

Operatori di filtro standard

L'API Web supporta gli operatori di filtro OData standard elencati nella tabella seguente:

Operator	Descrizione	Esempio
Operatori di confronto
eq	Uguale	$filter=revenue eq 100000
ne	Non uguale	$filter=revenue ne 100000
gt	Maggiore di	$filter=revenue gt 100000
ge	Maggiore di o uguale a	$filter=revenue ge 100000
lt	Minore di	$filter=revenue lt 100000
le	Minore di o uguale a	$filter=revenue le 100000
Operatori logici
and	And logico	$filter=revenue lt 100000 and revenue gt 2000
or	Or logico	$filter=contains(name,'(sample)') or contains(name,'test')
not	Negazione logica	$filter=not contains(name,'sample')
Operatori di raggruppamento
( )	Raggruppamento di precedenza	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Funzioni di query standard

L'API Web supporta queste funzioni di query stringa OData standard:

Funzione	Esempio
contiene	$filter=contains(name,'(sample)')
finisce con	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Funzioni di query Dataverse

L'API Web supporta le funzioni di query Dataverse per filtrare i risultati. Per altre informazioni, vedi Informazioni di riferimento sulle funzioni di query dell'API Web.

Ordina i risultati

Specifica l'ordine in cui gli elementi vengono restituiti utilizzando l'opzione di query di sistema $orderby . Utilizza il suffisso asc o desc per specificare rispettivamente l'ordine crescente o decrescente. L'impostazione predefinita è crescente se il suffisso non viene applicato. L'esempio seguente mostra il recupero del nome e delle proprietà dei ricavi degli account ordinati per ricavi crescenti e per nome decrescente.

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000`

Aggregare e raggruppare i risultati

Usando $apply, puoi aggregare e raggruppare i tuoi dati in modo dinamico come mostrato nei seguenti esempi:

Scenari	Esempio
Elenco degli stati univoci nella query	accounts?$apply=groupby((statuscode))
Somma aggregata del valore stimato	opportunities?$apply=aggregate(estimatedvalue with sum as total)
Dimensione media della transazione in base al valore e allo stato stimati	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Somma del valore stimato in base allo stato	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Ricavi opportunità totali per nome account	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Nomi dei contatti primari per gli account in "WA"	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data e ora creazione ultimo record	accounts?$apply=aggregate(createdon with max as lastCreate)
Data e ora creazione primo record	accounts?$apply=aggregate(createdon with min as firstCreate)

Recuperare un conteggio delle righe

Utilizza l'opzione di query di sistema $count con il valore Vero per includere un conteggio delle entità che corrispondono ai criteri di filtro fino a 5.000.

Method	URI
GET	`[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true`

Risposta di esempio

{
"@odata.count": 10,
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607"
    },
    {
    "@odata.etag": "W/\"1066414\"",
    "name": "Adventure Works (sample)",
    "accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
    }
]
}

Se non vuoi restituire nessun dato tranne il conteggio, puoi applicare $count a qualsiasi raccolta per ottenere solo il valore.

Method	URI
GET	`[Portal URI/_api/accounts/$count` Esempio: `https://contoso.powerappsportals.com/_api/accounts/$count`

Risposta di esempio

3

Confronto colonne

L'esempio seguente mostra come confrontare le colonne utilizzando l'API Web:

Method	URI
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` Esempio: `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

Recuperare i record della tabella correlati con una query

Utilizza l'opzione di query di sistema $expand nelle proprietà di spostamento per controllare quali dati vengono restituiti dalle entità correlate.

Proprietà di navigazione associata alla ricerca

Dovrai usare Microsoft.Dynamics.CRM.associatednavigationproperty come attributo di ricerca quando utilizzi l'opzione di query $expand.

Per determinare la proprietà Microsoft.Dynamics.CRM.associatednavigationproperty di un attributo, puoi effettuare la seguente richiesta http GET per la colonna utilizzando la seguente convenzione di denominazione: _name_value.

Nell'esempio seguente, possiamo determinare la proprietà di navigazione associata della colonna Contatto primario della tabella Account specificando il nome di colonna primarycontactid formattando il nome nella richiesta: _primarycontactid_value.

Method	URI
GET	`[Portal URI]/_api/accounts?$select=_primarycontactid_value` Esempio `https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value`

Risposta di esempio

{
"value": [
    {
        "@odata.etag": "W/\"2465216\"",
        "_primarycontactid_value@OData.Community.Display.V1.FormattedValue": "Yvonne McKay (sample)",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "primarycontactid",
        "_primarycontactid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "contact",
        "_primarycontactid_value": "417319b5-cd18-ed11-b83c-000d3af4d812",
        "accountid": "2d7319b5-cd18-ed11-b83c-000d3af4d812"
    }
]
}

Nella risposta è possibile osservare che la proprietà di navigazione associata è primarycontactid. La proprietà di navigazione associata può essere il nome logico o il nome di schema della colonna di ricerca a seconda di come è stata creata la tabella.

Per ulteriori informazioni, vedi Recuperare dati sulle proprietà di ricerca.

Recuperare i record della tabella correlati espandendo le proprietà di spostamento a valore singolo

L'esempio seguente mostra come recuperare il contatto per tutti i record dell'account. Per i relativi record di contatti, stiamo recuperando solo contactid e fullname.

Method	URI
GET	`[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)`

Risposta di esempio

{
"value": [
    {
    "@odata.etag": "W/\"1066412\"",
    "name": "Fourth Coffee (sample)",
    "accountid": "d2e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e6e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Yvonne McKay (sample)"
        }
    },
    {
    "@odata.etag": "W/\"1066413\"",
    "name": "Litware, Inc. (sample)",
    "accountid": "d4e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "primarycontactid": {
        "contactid": "e8e11ba8-92f6-eb11-94ef-000d3a5aa607",
        "fullname": "Susanna Stubberod (sample)"
        }
    }
]
}

Recuperare le tabelle correlate espandendo le proprietà di spostamento a valore raccolta

Se espandi i parametri di spostamento con valori di raccolta per recuperare le tabelle correlate per i set di entità, viene restituito un solo livello di profondità se sono presenti dati. In caso contrario, la raccolta restituirà un array vuoto.

Method	URI
GET	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)`

Recuperare le tabelle correlate espandendo le proprietà di spostamento a valore singolo e raccolta

L'esempio seguente mostra come espandere le entità correlate per i set di entità utilizzando proprietà di spostamento a valore singolo e raccolta. Dovrai specificare il nome della relazione della tabella nella sintassi del tuo codice.

Method	URI
GET	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)` Esempio: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)`

Passaggio successivo

Operazioni di scrittura, aggiornamento ed eliminazione dei portali con l'API Web

Vedi anche

Panoramica dell'API Web dei portali
Esercitazione: utilizzare l'API Web dei portali
Configurare le autorizzazioni di colonna

Nota

Puoi indicarci le tue preferenze di lingua per la documentazione? Partecipa a un breve sondaggio. (il sondaggio è in inglese)

Il sondaggio richiederà circa sette minuti. Non viene raccolto alcun dato personale (Informativa sulla privacy).

Condividi tramite

Query di dati utilizzando l'API Web dei portali

Prerequisiti

Query di record

Applicare le opzioni di query di sistema

Richiedere proprietà specifiche

Filtrare i risultati

Operatori di filtro standard

Funzioni di query standard

Funzioni di query Dataverse

Ordina i risultati

Aggregare e raggruppare i risultati

Recuperare un conteggio delle righe

Confronto colonne

Recuperare i record della tabella correlati con una query

Proprietà di navigazione associata alla ricerca

Recuperare i record della tabella correlati espandendo le proprietà di spostamento a valore singolo

Recuperare le tabelle correlate espandendo le proprietà di spostamento a valore raccolta

Recuperare le tabelle correlate espandendo le proprietà di spostamento a valore singolo e raccolta

Passaggio successivo

Vedi anche

Risorse aggiuntive