Consultes de dades amb l'API web de portals

Article
10/07/2023

Podeu utilitzar operacions API web disponibles a Power Pages. 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 lloc web 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. El primer s'afegeix després de [?] i les opcions de consulta següents se separen mitjançant [&]. 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'opció de consulta del sistema $select per limitar les propietats retornades 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'opció de consulta del sistema $filter per definir els criteris per als 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è voleu que es retornin els elements mitjançant l'opció de consulta del sistema $orderby. Utilitzeu 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

En utilitzar $apply, podeu agregar i agrupar les dades de manera dinàmica 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'opció de consulta del sistema $count amb un valor cert 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 llevat del recompte, podeu aplicar $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`

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

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.

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

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)`

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

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

Cercar una propietat de navegació associada

Pas següent

Consulteu també

Recursos addicionals

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