Compartir por

Consultar datos mediante a API web de portais

  • Artigo

Nota

A partir do 12 de outubro de 2022, Portais de Power Apps é Power Pages. Máis información: Microsoft Power Pages xa está dispoñible de forma xeral (blog)
Proximamente migraremos e uniremos a documentación de Portais de Power Apps coa documentación de Power Pages.

Pode usar as operacións de API web dispoñibles nos portais. As operacións da API web consisten en solicitudes e respostas HTTP. Este artigo proporciona operacións de lectura de exemplo, métodos, URI e o JSON de exemplo que pode usar na solicitude HTTP.

Requisitos previos

  • A súa versión do portal debe ser 9.4.1.x ou superior.

  • Active a táboa e o campo para as operacións da API web. Máis información: Axustes do sitio para a API web

  • A API web de portais accede aos rexistros de táboas e segue os permisos de táboa dados 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 faga referencia a táboas de Dataverse usando a API web de portais, cómpre usar EntitySetName, por exemplo, para acceder á táboa de conta, a sintaxe do código usará EntitySetName de contas.

Consultar rexistros

O seguinte exemplo consulta os rexistros da conta:

Operación Método URI
Recuperar rexistros da táboa GET [Portal URI]/_api/accounts

Exemplo:
 https://contoso.powerappsportals.com/_api/accounts

Resposta de exemplo

{
"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 as opcións de consulta do sistema $select e $top para devolver a propiedade do nome das tres primeiras contas:

Operación Método URI
Recuperar os tres primeiros rexistros de entidades GET [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 GET [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

Resposta de exemplo

{
    "@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 anexa ao URL do conxunto de entidades engádese mediante a sintaxe das cadeas de consulta. A primeira anéxase despois de [?] 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
GET [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

Propiedades específicas da solicitude

Use a opción de consulta do sistema $select para limitar as propiedades devoltas como se mostra no seguinte exemplo:

Método URI
GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

Exemplo:
https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3

Importante

É unha práctica recomendada do desempeño. Se non se especifican propiedades e configurou o valor de configuración do sitio Webapi/<table name>/fields en *, entón todas as propiedades serán devoltas usando $select. Se non se especifican propiedades, devolverase un erro.

Filtrar resultados

Use a opción de consulta do sistema $filter 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=revenue eq 100000
ne Diferente $filter=revenue ne 100000
gt Superior a $filter=revenue gt 100000
ge Maior que ou igual a $filter=revenue ge 100000
lt Inferior a $filter=revenue lt 100000
le Menor que ou igual a $filter=revenue le 100000
Operadores lóxicos
e "E" lóxico $filter=revenue lt 100000 and revenue gt 2000
or "Ou" lóxico $filter=contains(name,'(sample)') or contains(name,'test')
not Negación lóxica $filter=not contains(name,'sample')
Operadores de agrupamento
( ) Agrupación con precedencia (contains(name,'sample') or contains(name,'test')) and revenue 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 $filter=contains(name,'(sample)')
endswith $filter=endswith(name,'Inc.')
startswith $filter=startswith(name,'a')

Funcións de consulta de Dataverse

A API web é compatible con funcións de consulta de Dataverse para filtrar resultados. Para obter máis información, consulte Referencia da función de consulta da API web.

Ordenar resultados

Especifique a orde na que se devolven os elementos mediante a opción de consulta do sistema $orderby . Use o sufixo asc ou desc para especificar a orde ascendente ou descendente respectivamente. O valor 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
GET [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

Agregar e agrupar os resultados

Ao usar $apply, podes agregar e agrupar os teus datos de forma dinámica como se ve nos seguintes exemplos:

Escenarios Exemplo
Lista de estados únicos na consulta accounts?$apply=groupby((statuscode))
Agregar suma do valor estimado opportunities?$apply=aggregate(estimatedvalue with sum as total)
Tamaño medio do acordo en función do valor e o estado estimados opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with average as averagevalue)
Suma do valor estimado en función do estado opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue with sum as total))
Ingresos totais da oportunidade por nome da conta opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue with sum as total))
Nomes dos contactos principais para as contas en "WA" accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data e hora da última creación do rexistro accounts?$apply=aggregate(createdon with max as lastCreate)
Data e hora da primeira creación do rexistro accounts?$apply=aggregate(createdon with min as firstCreate)

Recuperar un reconto de filas

Use a opción de consulta do sistema $count con un valor de true para incluír un reconto de entidades que coincidan cos criterios de filtro ata 5.000.

Método URI
GET [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

Resposta de exemplo

{
"@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 aplicar $count a calquera colección para obter só o valor.

Método URI
GET [Portal URI/_api/accounts/$count

Exemplo:
https://contoso.powerappsportals.com/_api/accounts/$count

Resposta de exemplo

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

Recuperar rexistros de táboa relacionados cunha consulta

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

Busca da propiedade de navegación asociada

Terá que usar Microsoft.Dynamics.CRM.associatednavigationproperty como o atributo de busca ao usar a opción de consulta $expand.

Para determinar a Microsoft.Dynamics.CRM.associatednavigationproperty dun atributo, pode facer a seguinte solicitude http GET para a columna utilizando a seguinte convención de nomenclatura: _nome_valor.

No seguinte exemplo, podemos determinar a propiedade de navegación asociada da columna Contacto principal da táboa Conta especificando o nome da columna primarycontactid formatando o nome na solicitude: _primarycontactid_value.

Método URI
GET [Portal URI]/_api/accounts?$select=_primarycontactid_value

Exemplo
https://contoso.powerappsportals.com/_api/accounts?$select=_primarycontactid_value

Resposta de exemplo

{
"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 pola resposta que a propiedade de navegación asociada é primarycontactid. A propiedade de navegación asociada pode ser o nome lóxico ou nome do esquema da columna de busca dependendo de como foi creada a táboa.

Para máis información consulte Recuperar datos sobre propiedades de busca.

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

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

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)

Resposta de exemplo

{
"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 táboas relacionadas ampliando as propiedades de navegación con valor de colección

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

Recuperar táboas relacionadas ampliando as propiedades de navegación cun valor único ou cun valor de colección

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. Deberá especificar o nome da relación da táboa na sintaxe do seu código.

Método URI
GET [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

Operacións de escritura, actualización e eliminación de portais mediante a API web

Consulte tamén

Visión xeral da API web dos portais
Titorial: usar a API web dos portais
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).