Consultar datos utilizando la API web de portales
Nota
A partir del 12 de octubre de 2022, los portales de Power Apps son Power Pages. Más información: Microsoft Power Pages ya está disponible para el público en general (blog)
Pronto migraremos y fusionaremos la documentación de los portales de Power Apps con la documentación de Power Pages.
Puede usar las operaciones de API web disponibles en los portales. Las operaciones de la API web consisten en solicitudes y respuestas HTTP. Este artículo proporciona ejemplos de operaciones de lectura, métodos, URI y el JSON de muestra que puede usar en la solicitud HTTP.
Requisitos previos
La versión de su portal debe ser 9.4.1.x o superior.
Habilite la tabla y el campo para las operaciones de la API web. Más información: onfiguración de sitio para la API web
La API web de los portales accede a los registros de la tabla y sigue los permisos de la tabla otorgados a los usuarios a través de los roles web asociados. Asegúrese de configurar los permisos de tabla correctos. Más información: Crear roles web
Nota
Al referirse a tablas de Dataverse usando la API web del portal, necesita usar EntitySetName, por ejemplo, para acceder a la tabla cuenta, la sintaxis del código utilizará el EntitySetName de cuentas.
Consultar registros
El siguiente ejemplo consulta los registros de cuentas:
| Operación | Method | URI |
|---|---|---|
| Recuperar registros de tabla | OBTENER | [Portal URI]/_api/accountsEjemplo: https://contoso.powerappsportals.com/_api/accounts |
Respuesta de muestra
{
"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"
}
]
}
Use las opciones de consulta del sistema $select y $top para devolver la propiedad del nombre para las tres primeras cuentas:
| Operación | Method | URI |
|---|---|---|
| Recuperar los primeros tres registros de entidad | OBTENER | [Portal URI]/_api/accounts?$select=name,revenue&$top=3Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3 |
Recupere la cuenta usando el ID de la cuenta:
| Operación | Method | URI |
|---|---|---|
| Recuperar propiedad específica para un registro | OBTENER | [Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=nameEjemplo:https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name |
Respuesta de muestra
{
"@odata.etag": "W/\"1066414\"",
"name": "Adventure Works (sample)",
"accountid": "d6e11ba8-92f6-eb11-94ef-000d3a5aa607"
}
Aplicar opciones de consultas del sistema
Cada una de las opciones de consulta del sistema que anexa a la URL para el conjunto de entidades se agrega utilizando la sintaxis de cadenas de consulta. La primera se agrega después de [?] y las siguientes opciones de consulta se separan mediante [&]. Todas las opciones de consulta distinguen mayúsculas de minúsculas tal como se muestra en el siguiente ejemplo:
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3 |
Propiedades específicas de solicitud
Use la opción de consulta del sistema $select para limitar las propiedades devueltas tal como se muestra en el siguiente ejemplo:
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$select=name,revenue&$top=3Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3 |
Importante
Esta es una práctica recomendada de rendimiento. Si no se especifican las propiedades y ha configurado el valor de configuración de sitio Webapi/<table name>/fields en *, entonces todas las propiedades se devolverán usando $select. Si no se especifican propiedades, se devolverá un error.
Filtrar resultados
Use la opción de consulta del sistema $filter para establecer criterios por los que se devolverán filas.
Operadores estándar de filtro
La API web es compatible con los operadores de filtro OData estándar que se muestran en la tabla siguiente:
| Operator | Descripción | Ejemplo |
|---|---|---|
| Operadores de comparación | ||
| eq | Es igual a | $filter=revenue eq 100000 |
| ne | No es igual a | $filter=revenue ne 100000 |
| gt | Mayor que | $filter=revenue gt 100000 |
| ge | Mayor o igual que | $filter=revenue ge 100000 |
| lt | Menor que | $filter=revenue lt 100000 |
| le | Menor o igual que | $filter=revenue le 100000 |
| Operadores lógicos | ||
| and | Lógico y | $filter=revenue lt 100000 y revenue gt 2000 |
| or | Disyunción lógica | $filter=contains(name,'(sample)') o contains(name,'test') |
| not | Negación lógica | $filter=not contains(name,'sample') |
| Agrupación de operadores | ||
| ( ) | Agrupaciones por prioridad | (contains(name,'sample') o contains(name,'test')) y revenue gt 5000 |
Funciones estándar de consulta
La API web admite estas funciones de consulta de cadena de OData estándar:
| Función | Ejemplo |
|---|---|
| contiene | $filter=contains(name,'(sample)') |
| endswith | $filter=endswith(name,'Inc.') |
| startswith | $filter=startswith(name,'a') |
Funciones de consulta de Dataverse
La API web admite funciones de consulta de Dataverse para filtrar los resultados. Para obtener más información, consulte Referencia de función de consulta de API web.
Ordenar resultados
Especifique el orden en que los elementos se devuelven mediante la opción de consulta del sistema $orderby . Use el sufijo asc o desc para especificar orden ascendente o descendente respectivamente. El valor predeterminado es ascendente si no se aplica el sufijo. El ejemplo siguiente muestra la recuperación de propiedades de nombre e ingresos de cuentas ordenadas por ingreso ascendente y por nombre descendente.
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000 |
Resultados agregados y agrupados
Mediante el uso de $apply puede agregar y agrupar sus datos dinámicamente como se ve en los siguientes ejemplos:
| Escenarios | Ejemplo |
|---|---|
| Lista de estados únicos en la consulta | accounts?$apply=groupby((statuscode)) |
| Suma agregada del valor estimado | opportunities?$apply=aggregate(estimatedvalue with sum as total) |
| Tamaño medio del negocio basado en valor y estado estimados | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue) |
| Suma de valor estimado basado en estado | opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total)) |
| Ingresos totales de la oportunidad por nombre de cuenta | opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total)) |
| Nombres de contacto primario para cuentas de “WA” | accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname)) |
| Fecha y hora de registro creado por última vez | accounts?$apply=aggregate(createdon with max as lastCreate) |
| Fecha y hora de registro creado por primera vez | accounts?$apply=aggregate(createdon with min as firstCreate) |
Recuperar un recuento de filas
Use la opción de consulta del sistema $count con un valor de True para incluir un recuento de entidades que coincidan con los criterios de filtro hasta 5000.
| Method | URI |
|---|---|
| OBTENER | [Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=trueEjemplo:https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true |
Respuesta de muestra
{
"@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 desea que se devuelva ningún dato excepto el recuento, puede aplicar $count a cualquier colección para obtener únicamente el valor.
| Method | URI |
|---|---|
| OBTENER | [Portal URI/_api/accounts/$countEjemplo:https://contoso.powerappsportals.com/_api/accounts/$count |
Respuesta de muestra
3
Comparación de columnas
El siguiente ejemplo muestra cómo comparar columnas usando la API web:
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastnameEjemplo:https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname |
Recuperar registros de tabla relacionados con una consulta
Use la opción de consulta del sistema $expand en las propiedades de navegación para controlar qué datos de entidades relacionadas se devuelven.
Propiedad de navegación asociada de búsquedas
Deberá utilizar Microsoft.Dynamics.CRM.associatednavigationproperty como atributo de búsqueda cuando use la opción de consulta $expand.
Para determinar Microsoft.Dynamics.CRM.associatednavigationproperty de un atributo, puede realizar la siguiente solicitud GET http para la columna utilizando la siguiente convención de nomenclatura: _nombre_valor.
En el siguiente ejemplo, podemos determinar la propiedad de navegación asociada de la columna Contacto primario de la tabla Cuenta especificando el nombre de la columna primarycontactid formateando el nombre en la solicitud: _primarycontactid_value.
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$select=_primarycontactid_valueEjemplohttps://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value |
Respuesta de muestra
{
"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"
}
]
}
Vemos en la respuesta que la propiedad de navegación asociada es primarycontactid. La propiedad de navegación asociada puede ser la columna de búsqueda nombre lógico o nombre de esquema dependiendo de cómo se creó la tabla.
Para más información, vea Recuperar datos sobre propiedades de búsqueda.
Recuperar registros de tabla relacionados ampliando las propiedades de navegación con un valor
El ejemplo siguiente muestra cómo recuperar el contacto para todos los registros de la cuenta. Para los registros de contacto relacionados, solo recuperamos contactid y fullname.
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname) |
Respuesta de muestra
{
"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 tablas relacionadas ampliando las propiedades de navegación de una colección
Si expande parámetros de navegación valorados como colección para recuperar tablas relacionadas para conjuntos de entidades, solo se devuelve un nivel de profundidad si hay datos. De lo contrario, la colección devolverá una matriz vacía.
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart) |
Recuperar tablas relacionadas para una instancia de entidad expandiendo las propiedades de navegación valoradas tanto como de un valor como colección
El siguiente ejemplo muestra cómo puede expandir entidades relacionadas para los conjuntos de entidad mediante propiedades de navegación únicas o de colección. Deberá especificar el nombre de la relación de la tabla en la sintaxis de su código.
| Method | URI |
|---|---|
| OBTENER | [Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)Ejemplo:https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart) |
Paso siguiente
Operaciones de escritura, actualización y eliminación de portales con la API web
Consulte también
Información general de API web de portales Tutorial: Uso del API web del portal Configurar permisos de columna
Nota
¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)
La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de