Consultes de dades amb l'API web de portals

Article
12/24/2024

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	REBRE	`[Portal URI]/_api/accounts` Exemple: `https://contoso.powerappsportals.com/_api/accounts`

Exemple de resposta

{
"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	REBRE	`[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	REBRE	`[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`

Exemple de resposta

{
    "@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 següents opcions de consulta es 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
REBRE	`[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
REBRE	`[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ó $filter consulta del sistema per definir els criteris per a les files que es retornen.

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=EQ d'ingressos 100000
ne	No és igual	$filter=ingressos ne 100000
gt	Major que	$filter=Ingressos GT 100000
ge	Major o igual que	$filter=ingressos ge 100000
lt	Menor que	$filter=ingressos lt 100000
le	Menor o igual que	$filter=ingressos le 100000
Operadors lògics
i la	I lògic	$filter=Ingressos LT 100000 i Ingressos GT 2000
o bé	O lògic	$filter=conté(nom,'(mostra)') o conté(nom,'prova')
no	Negació lògica	$filter=no conté(nom,'mostra')
Agrupació d'operadors
( )	Agrupament de prioritats	(conté(nom,'mostra') o conté(nom,'prova')) i ingressos 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=conté(nom,'(mostra)')
endswith	$filter=endswith(nom,'Inc.')
Comença amb	$filter=comença amb(nom,'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
REBRE	`[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	comptes?$apply=groupby((codi d'estat))
Suma agregada del valor estimat	oportunitats?$apply=aggregate(estimatedvalue amb suma com a total)
Mida mitjana de l'acord segons el valor i l'estat previstos	oportunitats?$apply=groupby((codi d'estat),aggregate(estimatedvalue amb mitjana com a valor mitjà)
Suma del valor estimat segons l'estat	oportunitats?$apply=groupby((codi d'estat),aggregate(estimatedvalue amb suma com a total))
Ingressos totals de l'oportunitat per nom de compte	oportunitats?$apply=groupby((parentaccountid/nom),aggregate(estimatedvalue amb suma com a total))
Noms de contacte principals dels comptes a 'WA'	comptes?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data i hora del darrer registre creat	comptes?$apply=aggregate(createdon amb max com lastCreate)
Data i hora del primer registre creat	comptes?$apply=aggregate(creaton amb min com a 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
REBRE	`[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`

Exemple de resposta

{
"@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
REBRE	`[Portal URI/_api/accounts/$count` Exemple: `https://contoso.powerappsportals.com/_api/accounts/$count`

Exemple de resposta

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.

Heu d'utilitzar Microsoft.Dynamics.CRM.associatednavigationcom a atribut de cerca quan utilitzeu l'opció $expand consulta.

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`

Exemple de resposta

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

Exemple de resposta

{
"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. En cas contrari, la col·lecció retorna una matriu buida.

Mètode	URI
REBRE	`[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ó. Heu d'especificar el nom de la relació de taula a la sintaxi del vostre codi.

Mètode	URI
REBRE	`[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)`

Consulta de registres mitjançant FetchXml

Passar la consulta FetchXml com a valor de cadena codificat per URL a la col·lecció de conjunts d'entitats mitjançant el paràmetre de consulta FetchXml.

Per exemple, per recuperar dades del conjunt d'entitats delcompte, redacteu una consulta FetchXml definint el paràmetre de nom de l'element d'entitat al compte.

<fetch top='2'>
  <entity name='account'>
      <attribute name='name' />
  </entity>
</fetch>

La cadena codificada per URL per a la consulta anterior és:

%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E

Mètode	URI
REBRE	`[Portal URI]/_api/accounts?fetchxml` Exemple: `https://contoso.powerappsportals.com/_api/accounts?fetchXml=%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E`

Exemple de resposta

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

Pas següent

Els portals escriuen, actualitzen i suprimeixen operacions mitjançant 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

Consulta de registres mitjançant FetchXml

Pas següent

Consulteu també

Comentaris

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ó

Consulta de registres mitjançant FetchXml

Pas següent

Consulteu també

Comentaris

Recursos addicionals