Consultar datos utilizando la API web de portales

Artículo
03/16/2023

Puede usar las operaciones de API web disponibles en Power Pages. 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 del sitio web 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	GET	`[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	GET	`[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	GET	`[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
GET	`[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
GET	`[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 and revenue gt 2000
or	Disyunción lógica	$filter=contains(name,'(sample)') or contains(name,'test')
not	Negación lógica	$filter=not contains(name,'sample')
Agrupación de operadores
( )	Agrupaciones por prioridad	(contains(name,'sample') or contains(name,'test')) and 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
GET	`[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 Verdadero para incluir un recuento de entidades que coincidan con los criterios de filtro hasta 5000.

Method	URI
GET	`[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
GET	`[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`

Use la opción de consulta del sistema $expand en las propiedades de navegación para controlar qué datos de entidades relacionadas se devuelven.

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.

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

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

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
GET	`[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

Compartir a través de

Consultar datos utilizando la API web de portales

Requisitos previos

Consultar registros

Aplicar opciones de consultas del sistema

Propiedades específicas de solicitud

Filtrar resultados

Operadores estándar de filtro

Funciones estándar de consulta

Funciones de consulta de Dataverse

Ordenar resultados

Resultados agregados y agrupados

Recuperar un recuento de filas

Comparación de columnas

Propiedad de navegación asociada de búsquedas

Paso siguiente

Consulte también

Comentarios

Recursos adicionales

Compartir a través de

Consultar datos utilizando la API web de portales

Requisitos previos

Consultar registros

Aplicar opciones de consultas del sistema

Propiedades específicas de solicitud

Filtrar resultados

Operadores estándar de filtro

Funciones estándar de consulta

Funciones de consulta de Dataverse

Ordenar resultados

Resultados agregados y agrupados

Recuperar un recuento de filas

Comparación de columnas

Recuperar registros de tabla relacionados con una consulta

Propiedad de navegación asociada de búsquedas

Recuperar registros de tabla relacionados ampliando las propiedades de navegación con un valor

Recuperar tablas relacionadas ampliando las propiedades de navegación de una colección

Recuperar tablas relacionadas para una instancia de entidad expandiendo las propiedades de navegación valoradas tanto como de un valor como colección

Paso siguiente

Consulte también

Comentarios

Recursos adicionales