Consulta les dades mitjançant l'API web dels portals (visualització prèvia)

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

Important

  • Aquesta és una característica de visualització prèvia.
  • Les característiques de visualització prèvia no estan dissenyades per a un entorn de producció i poden tenir una funcionalitat restringida. Aquestes característiques estan disponibles abans d’un llançament oficial de producte per tal que els clients el puguin utilitzar abans i enviar-nos els seus comentaris.
  • Un cop habilitada aquesta característica, les taules i columnes configurades a la configuració del lloc per a l'API web estaran disponibles per a les operacions de lectura.

Requisits previs

  • Habilita 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 donats als usuaris a través de les funcions web associades. Assegureu-vos que configureu els permisos de la taula correctes. Més informació: Crear rols web

Configuració del lloc per a operacions de lectura de l'API web

Heu de configurar la configuració del lloc WebAPI/enableReadOperationPreview i definir-ne el valor com a Cert per habilitar les operacions de lectura mitjançant l'API web dels portals.

Habilita la configuració del lloc de lectura de l'API web.

Important

Aquesta configuració del lloc només és necessària durant el període de visualització prèvia.

Registres de consulta

Els registres de compte de consultes d'exemple següents:

Operació Mètode URI
Recupera els registres de la taula REBRE [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 $select i $top opcions de consulta del sistema per retornar la propietat nom dels tres primers comptes:

Operació Mètode URI
Recupera 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

Recupera el compte mitjançant l'identificador del compte:

Operació Mètode URI
Recupera una propietat específica per a 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

Resposta d'exemple

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

Aplica les 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 per a 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 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·licita 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

És una pràctica de rendiment. Si les propietats no s'especifiquen i heu configurat el valor de configuració del Webapi/<table name>/fields lloc a, totes les propietats es * retornaran mitjançant $select. Si no s'especifica cap propietat, es retornarà un error.

Resultats del filtre

Utilitzeu l'opció de consulta del sistema $filter per establir criteris per a quines files es retornaran.

Operadors de filtres estàndard

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

Operador Descripció Exemple
Operadors de comparació
eq Igual $filter=ingressos eq 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 Lògic i $filter=ingressos lt 100000 i ingressos gt 2000
o bé Lògic o $filter=conté(nom,'(mostra)') o conté(nom,'test')
no Negació lògica $filter=no conté(nom,'mostra')
Operadors d'agrupació
( ) Agrupació de precedència (conté(nom,'exemple') o conté(nom,'prova')) i ingressos gt 5000

Funcions de consulta estàndard

L'API web és compatible amb aquestes funcions estàndard de consulta de cadenes OData:

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

Resultats de la comanda

Especifiqueu l'ordre en què es retornen els elements 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 no s'aplica el sufix. L'exemple següent mostra la recuperació del nom i les propietats d'ingressos dels comptes ordenats pels ingressos ascendents i pel 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

Resultats agregats i agrupats

Si utilitzeu $apply, podeu agregar i agrupar les dades dinàmicament com es veu als exemples següents:

Escenaris Exemple
Llista d'estats únics de la consulta comptes?$apply=groupby((statuscode))
Suma agregada del valor estimat oportunitats?$apply=aggregate(valor estimat amb la suma com a total)
Mida mitjana de l'acord en funció del valor estimat i l'estat oportunitats?$apply=groupby((statuscode),aggregate(valor estimat amb la mitjana com a valor mitjà)
Suma del valor estimat en funció de l'estat oportunitats?$apply=groupby((statuscode),aggregate(valor estimat amb la suma com a total))
Total d'ingressos d'oportunitat per nom del compte oportunitats?$apply=groupby((parentaccountid/name),aggregate(valor estimat amb suma com a total))
Noms de contacte principals per als comptes de 'WA' accounts?$apply=filter(address1 _ stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data i hora del registre creat per última vegada comptes?$apply=aggregate(creat amb màx. com a últimCrear)
Data i hora del registre creats per primera vegada comptes?$apply=aggregate(createdon amb min com a primerCrear)

Recupera un recompte de files

Utilitzeu l'opció de consulta del sistema $count 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
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

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 tornar cap dada excepte el recompte, podeu sol·licitar $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

Resposta d'exemple

3

Comparació de columnes

L'exemple següent mostra com comparar columnes mitjançant 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.

L'exemple següent mostra com recuperar el contacte de tots els registres de compte. Per als registres de contacte relacionats, només estem recuperant el contactid i el nom complet ·.

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 amplieu els paràmetres de navegació valorats en la col·lecció per recuperar taules relacionades per als conjunts d'entitats, només es retornarà un nivell de profunditat si hi ha dades. En cas contrari, la col·lecció retornarà 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 mostra com podeu ampliar les entitats relacionades per als conjunts d'entitats utilitzant propietats de navegació úniques i valorades per la col·lecció.

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)

Pas següent

Els portals escriuen, actualitzen i suprimeixen operacions mitjançant l'API web

Consulteu també

Informació general sobre l’API web de portals
Tutorial: Utilitza l'API web del portal