Consulta datos mediante a API web de portais

Artigo
08/02/2022
3 minutos de lectura

Podes usar operacións da API web dispoñibles en portais. As operacións da API web consisten en solicitudes e respostas HTTP. Este artigo ofrece exemplos de operacións de lectura, métodos, URI e JSON de mostra que podes usar na solicitude HTTP.

Requisitos previos

A versión do teu portal debe ser 9.4.1.x ou superior.
Activa a táboa e o campo para as operacións da API web. Máis información: Configuración do sitio para a API web
A API web de portais accede aos rexistros das táboas e segue os permisos das táboas concedidos aos usuarios a través dos roles web asociados. Asegúrese de configurar os permisos de táboa correctos. Máis información: Crear roles web

Nota

Cando se refire Dataverse táboas usando a API web de portais, cómpre usar o EntitySetName, por exemplo, para acceder ao conta táboa, a sintaxe do código usará o EntitySetName de contas.

Consulta rexistros

O seguinte exemplo consulta os rexistros da conta:

Operación	Método	URI
Recuperar rexistros da táboa	CONSEGUIR	`[Portal URI]/_api/accounts` Exemplo: `https://contoso.powerappsportals.com/_api/accounts`

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

Use $seleccionar e $arriba opcións de consulta do sistema para devolver a propiedade do nome das tres primeiras contas:

Operación	Método	URI
Recupera os tres primeiros rexistros de entidades	CONSEGUIR	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Recuperar a conta usando o ID da conta:

Operación	Método	URI
Recuperar propiedades específicas para un rexistro	CONSEGUIR	`[Portal URI]/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name` Exemplo: `https://contoso.powerappsportals.com/_api/accounts(e0e11ba8-92f6-eb11-94ef-000d3a5aa607)?$select=name`

Exemplo de resposta

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

Aplicar opcións de consulta do sistema

Cada unha das opcións de consulta do sistema que engádese ao URL do conxunto de entidades engádese mediante a sintaxe para as cadeas de consulta. O primeiro engádese despois[?] e as seguintes opcións de consulta sepáranse mediante [&]. Todas as opcións de consulta distinguen entre maiúsculas e minúsculas, como se mostra no seguinte exemplo:

Método	URI
CONSEGUIR	`[Portal URI]/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$filter=revenue gt 90000&$top=3`

Solicitar propiedades específicas

Usa o $seleccionar opción de consulta do sistema para limitar as propiedades devoltas como se mostra no seguinte exemplo:

Método	URI
CONSEGUIR	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Importante

Esta é unha boa práctica de rendemento. Se non se especifican propiedades e configurou oWebapi/<table name>/fields valor de configuración do sitio para*, entón todas as propiedades serán devoltas usando $select. Se non se especifican propiedades, devolverase un erro.

Filtrar resultados

Usa o $filtro opción de consulta do sistema para establecer os criterios para os que se devolverán as filas.

Operadores de filtro estándar

A API web admite os operadores de filtro OData estándar que se indican na seguinte táboa:

Operador	Descripción	Exemplo
Operadores de comparación
eq	Igual que	$filter=eq de ingresos 100000
ne	Non Iguais	$filter=revenue ne 100000
gt	Superior a	$filter=ingresos gt 100000
xe	Maior que ou igual a	$filter=ingresos ge 100000
lt	Inferior a	$filter=ingresos lt 100000
le	Menor que ou igual a	$filter=revenue le 100000
Operadores lóxicos
e	Lóxico e	$filter=revenue lt 100000 e ingresos gt 2000
or	Lóxico ou	$filtro=contén (nome, '(mostra)') ou contén (nome, 'proba')
non	Negación lóxica	$filtro=non contén (nome, 'mostra')
Agrupación de operadores
( )	Agrupación de precedencia	(contén (nome, 'mostra') ou contén (nome, 'proba')) e ingresos gt 5000

Funcións de consulta estándar

A API web admite estas funcións estándar de consulta de cadeas OData:

Función	Exemplo
contén	$filtro=contén(nome,'(mostra)')
endswith	$filter=endswith(nome,'Inc.')
startswith	$filtro=comeza con(nome,'a')

Orde de resultados

Especifique a orde na que se devolven os artigos mediante a $ordenby opción de consulta do sistema. Usa o asc ou desc sufixo para especificar a orde ascendente ou descendente respectivamente. O predeterminado é ascendente se non se aplica o sufixo. O seguinte exemplo mostra a recuperación do nome e das propiedades dos ingresos das contas ordenadas por ingresos ascendentes e por nome descendente.

Método	URI
CONSEGUIR	`[Portal URI]/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$orderby=name asc,revenue desc&$filter=revenue gt 90000`

Agrega e agrupa os resultados

Mediante o uso $aplicar, pode agregar e agrupar os seus datos de forma dinámica como se ve nos seguintes exemplos:

Escenarios	Exemplo
Lista de estados únicos na consulta	contas?$apply=groupby((código de estado))
Suma agregada do valor estimado	oportunidades?$apply=agregado(valor estimado coa suma como total)
Tamaño medio do acordo en función do valor e o estado estimados	oportunidades?$apply=groupby((código de estado),agregado(valor estimado coa media como valor medio)
Suma do valor estimado en función do estado	oportunidades?$apply=groupby((código de estado),agregado(valor estimado coa suma como total))
Ingresos totais da oportunidade por nome da conta	oportunidades?$apply=groupby((identificador/nome da conta do pai), agregado(valor estimado coa suma como total))
Nomes dos contactos principais para as contas en "WA"	contas?$apply=filtro(enderezo1_ stateorprovince eq 'WA')/groupby((contacto principal/nome completo))
Data e hora do último rexistro creado	contas?$apply=aggregate(creado con max como lastCreate)
A primeira data e hora do rexistro creado	contas?$apply=aggregate(creado con min como firstCreate)

Recuperar un reconto de filas

Usa o $conto opción de consulta do sistema cun valor verdadeiro para incluír un reconto de entidades que coincidan cos criterios de filtro ata 5.000.

Método	URI
CONSEGUIR	`[Portal URI/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$filter=contains(name,'sample')&$count=true`

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

Se non queres devolver ningún dato excepto o reconto, podes solicitar $conto a calquera colección para obter só o valor.

Método	URI
CONSEGUIR	`[Portal URI/_api/accounts/$count` Exemplo: `https://contoso.powerappsportals.com/_api/accounts/$count`

Exemplo de resposta

3

Comparación de columnas

O seguinte exemplo mostra como comparar columnas usando a API web:

Método	URI
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` Exemplo: `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

Usa o $expand opción de consulta do sistema nas propiedades de navegación para controlar que datos de entidades relacionadas se devolven.

O seguinte exemplo mostra como recuperar o contacto para todos os rexistros da conta. Para os rexistros de contacto relacionados, só estamos recuperando o contactoid e nome completo.

Método	URI
GET	`[Portal URI]/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name&$expand=primarycontactid($select=contactid,fullname)`

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

Se amplía os parámetros de navegación con valores de colección para recuperar táboas relacionadas para conxuntos de entidades, só se devolve un nivel de profundidade se hai datos. En caso contrario, a colección devolverá unha matriz baleira.

Método	URI
CONSEGUIR	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=Account_Tasks($select=subject,scheduledstart)`

O seguinte exemplo mostra como pode expandir as entidades relacionadas para conxuntos de entidades utilizando propiedades de navegación únicas e con valores de colección.

Método	URI
CONSEGUIR	`[Portal URI]/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$top=5&$select=name&$expand=primarycontactid($select=contactid,fullname),Account_Tasks($select=subject,scheduledstart)`

Seguinte paso

Os portais escriben, actualizan e eliminan operacións mediante a API web

Consulte tamén

Visión xeral da API web dos portais
Titorial: Usa a API web do portal
Configurar permisos de columnas

Nota

Pode indicarnos as súas preferencias para o idioma da documentación? Realice unha enquisa breve. (teña en conta que esa enquisa está en inglés)

Esta enquisa durará sete minutos aproximadamente. Non se recompilarán datos persoais (declaración de privacidade).

Consulta datos mediante a API web de portais

Requisitos previos

Consulta rexistros

Aplicar opcións de consulta do sistema

Solicitar propiedades específicas

Filtrar resultados

Operadores de filtro estándar

Funcións de consulta estándar

Orde de resultados

Agrega e agrupa os resultados

Recuperar un reconto de filas

Comparación de columnas

Recuperar rexistros de táboa relacionados cunha consulta

Recupera rexistros de táboas relacionados ampliando as propiedades de navegación dun único valor

Recupera táboas relacionadas ampliando as propiedades de navegación con valores de colección

Recupera táboas relacionadas ampliando as propiedades de navegación de valor único e de colección

Seguinte paso

Consulte tamén

Comentarios