Compartir vía

Consultar datos utilizando la API web de portales

  • Artículo

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/accounts

Ejemplo:
 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=3

Ejemplo:
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=name

Ejemplo:
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=3

Ejemplo:
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=3

Ejemplo:
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 90000

Ejemplo:
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=true

Ejemplo:
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/$count

Ejemplo:
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 lastname

Ejemplo:
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_value

Ejemplo
https://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).