Consultes de dades amb l'API web de portals

Article
03/14/2023

Nota

Des del 12 d'octubre de 2022, els portals del Power Apps són Power Pages. Més informació: Microsoft Power Pages ara està disponible de manera general (bloc)
Ben aviat migrarem i combinarem la documentació dels portals del Power Apps amb la documentació del Power Pages.

Podeu utilitzar operacions API web disponibles als portals. Les operacions de l'API web consisteixen en sol·licituds i respostes HTTP. En aquest article s'ofereixen operacions de lectura, mètodes, URI i JSON d'exemple que podeu utilitzar a la sol·licitud HTTP.

Requisits previs

La versió del portal ha de ser la 9.4.1.x o superior.
Habilitar la taula i el camp per a les operacions de l'API web. Més informació: Configuració del lloc per a l'API web
L'API web dels portals accedeix als registres de taula i segueix els permisos de taula atorgats als usuaris mitjançant les funcions web associades. Assegureu-vos de configurar els permisos de taula correctes. Més informació: Crear funcions web

Nota

Quan feu referència a taules del Dataverse que utilitzen l'API web de portals, heu d'utilitzar EntitySetName; per exemple, per accedir a la taula compte, la sintaxi de codi utilitzarà l'EntitySetName comptes.

Consultar registres

A l'exemple següent es consulten els registres de compte:

Operació	Mètode	URI
Recuperar registres de taula	GET	`[Portal URI]/_api/accounts` Exemple: `https://contoso.powerappsportals.com/_api/accounts`

Resposta d'exemple

{
"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"
    }
]
}

Utilitzeu les opcions de consulta del sistema $select i $top per retornar la propietat de nom dels tres primers comptes:

Operació	Mètode	URI
Recuperar els tres primers registres d'entitat	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Exemple: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Recuperar el compte mitjançant l'ID del compte:

Operació	Mètode	URI
Recuperar una propietat específica d'un registre	GET	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Exemple: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Resposta d'exemple

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

Aplicar opcions de consulta del sistema

Cadascuna de les opcions de consulta del sistema que afegiu a l'adreça URL del conjunt d'entitats s'afegeix amb la sintaxi de les cadenes de consulta. La primera s'annexa després de [?] i les següents opcions de consulta se separen amb [&]. Totes les opcions de consulta distingeixen entre majúscules i minúscules, tal com es mostra a l'exemple següent:

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

Sol·licitar propietats específiques

Utilitzeu l$select **** opció de consulta del sistema per limitar les propietats retornades tal com es mostra a l'exemple següent:

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

Important

Això és una pràctica recomanada de rendiment. Si les propietats no s'especifiquen i heu configurat el valor de configuració del lloc Webapi/<table name>/fields en *, totes les propietats es retornaran amb $select. Si no s'especifica cap propietat, es retornarà un error.

Filtra els resultats

Utilitzeu l$filter **** opció de consulta del sistema per establir criteris per a les quals es retornaran les files.

Operadors de filtre estàndard

L'API web admet els operadors de filtre d'OData estàndard enumerats a la taula següent:

Operador	Descripció	Exemple
Operadors de comparació
eq	Igual	$filter=revenue eq 100000
ne	No és igual	$filter=revenue ne 100000
gt	Major que	$filter=revenue gt 100000
ge	Major o igual que	$filter=revenue ge 100000
lt	Menor que	$filter=revenue lt 100000
le	Menor o igual que	$filter=revenue le 100000
Operadors lògics
i la	I lògic	$filter=revenue lt 100000 and revenue gt 2000
o bé	O lògic	$filter=contains(name,'(sample)') or contains(name,'test')
no	Negació lògica	$filter=not contains(name,'sample')
Operadors d'agrupació
( )	Agrupament de prioritats	(contains(name,'sample') or contains(name,'test')) and revenue gt 5000

Funcions de consulta estàndard

L'API web admet aquestes funcions estàndard de consulta de cadena d'OData:

Funció	Exemple
conté	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
Comença amb	$filter=startswith(name,'a')

Funcions de consulta del Dataverse

L'API web admet funcions de consulta del Dataverse per filtrar els resultats. Per obtenir més informació, vegeu Referència de funcions de consulta de l'API web.

Ordenar els resultats

Especifiqueu l'ordre en què es retornen els articles mitjançant l'opció de consulta del sistema$orderby . Utilitzeu el sufix asc o desc per especificar l'ordre ascendent o descendent respectivament. El valor per defecte és ascendent si el sufix no s'aplica. A l'exemple següent es mostra la recuperació de les propietats de nom i ingressos dels comptes ordenats per ingressos ascendents i per nom descendent.

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

Agregar i agrupar resultats

Mitjançant $apply , podeu agregar i agrupar les dades dinàmicament tal com es veu en els exemples següents:

Escenaris	Exemple
Llista d'estats únics a la consulta	accounts?$apply=groupby((statuscode))
Suma agregada del valor estimat	opportunities?$apply=aggregate(estimatedvalue with sum as total)
Mida mitjana de l'acord segons el valor i l'estat previstos	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Suma del valor estimat segons l'estat	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Ingressos totals de l'oportunitat per nom de compte	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Noms de contacte principals dels comptes a 'WA'	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data i hora del darrer registre creat	accounts?$apply=aggregate(createdon with max as lastCreate)
Data i hora del primer registre creat	accounts?$apply=aggregate(createdon with min as firstCreate)

Recuperar un recompte de files

Utilitzeu l$count **** opció de consulta del sistema amb un valor de true per incloure un recompte d'entitats que coincideixin amb els criteris de filtre fins a 5.000.

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

Resposta d'exemple

{
"@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"
    }
]
}

Si no voleu retornar cap dada excepte el recompte, podeu sol·licitar $count a qualsevol col·lecció per obtenir només el valor.

Mètode	URI
GET	`[Portal URI/_api/accounts/$count` Exemple: `https://contoso.powerappsportals.com/_api/accounts/$count`

Resposta d'exemple

3

Comparació de columnes

A l'exemple següent es mostra com comparar les columnes amb l'API web:

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

Recuperar registres de taula relacionats amb una consulta

Utilitzeu l$expand **** opció de consulta del sistema a les propietats de navegació per controlar quines dades d'entitats relacionades es retornen.

Cercar una propietat de navegació associada

Haureu d'utilitzar Microsoft.Dynamics.CRM.associatednavigationproperty com a atribut de cerca quan utilitzeu l'opció de consulta $expand.

Per determinar la Microsoft.Dynamics.CRM.associatednavigationproperty d'un atribut, podeu fer la sol·licitud GET http següent per a la columna utilitzant la convenció de nomenclatura següent : _name_value.

A l'exemple següent, podem determinar la propietat de navegació associada de la columna Contacte principal de la taula Compte especificant el nom de columna primarycontactid formatant el nom a la sol·licitud: _primarycontactid_value.

Mètode	URI
GET	`[Portal URI]/_api/accounts?$select=_primarycontactid_value` Exemple `https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value`

Resposta d'exemple

{
"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"
    }
]
}

Veiem a la resposta que la propietat de navegació associada és primarycontactid. La propietat de navegació associada pot ser el nom lògic o el nom de l'esquema de la columna de cerca, en funció de com es va crear la taula.

Per obtenir més informació, vegeu Recuperar dades sobre les propietats de cerca.

Recuperar registres de taula relacionats expandint les propietats de navegació d'un sol valor

A l'exemple següent es mostra com recuperar el contacte de tots els registres de compte. Per als registres de contacte relacionats, només es recupera contactid i fullname.

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

Resposta d'exemple

{
"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)"
        }
    }
]
}

Recuperar taules relacionades expandint les propietats de navegació amb valor de col·lecció

Si expandiu els paràmetres de navegació amb valor de col·lecció per recuperar les taules relacionades per als conjunts d'entitats, només es retorna un nivell de profunditat si hi ha dades. Altrament, la col·lecció retornarà una matriu buida.

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

Recuperar taules relacionades expandint les propietats de navegació d'un sol valor i de valor de col·lecció

L'exemple següent explica com podeu expandir les entitats relacionades per als conjunts d'entitats utilitzant les propietats de navegació d'un sol valor o de valor de col·lecció. Haureu d'especificar el nom de la relació de taula a la sintaxi del codi.

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

Pas següent

Operacions d'escriptura, actualització i supressió al Portals amb l'API web

Consulteu també

Informació general sobre l'API web de portals
Tutorial: Utilitzar l'API web del portal
Configurar permisos de columna

Nota

Ens podeu dir quines són les vostres preferències d'idioma per a la documentació? Responeu una breu enquesta. (tingueu en compte que l'idioma de l'enquesta és l'anglès)

Trigareu uns set minuts a completar l'enquesta. No es recopilen dades personals (declaració de privadesa).

Comparteix a través de

Consultes de dades amb l'API web de portals

Requisits previs

Consultar registres

Aplicar opcions de consulta del sistema

Sol·licitar propietats específiques

Filtra els resultats

Operadors de filtre estàndard

Funcions de consulta estàndard

Funcions de consulta del Dataverse

Ordenar els resultats

Agregar i agrupar resultats

Recuperar un recompte de files

Comparació de columnes

Recuperar registres de taula relacionats amb una consulta

Cercar una propietat de navegació associada

Recuperar registres de taula relacionats expandint les propietats de navegació d'un sol valor

Recuperar taules relacionades expandint les propietats de navegació amb valor de col·lecció

Recuperar taules relacionades expandint les propietats de navegació d'un sol valor i de valor de col·lecció

Pas següent

Consulteu també

Recursos addicionals