Consultar dados usando portais API Web

Artigo
03/15/2023

Observação

Desde o dia 12 de outubro de 2022, os portais do Power Apps passaram a ser Power Pages. Mais Informações: O Microsoft Power Pages já está disponível para todos (blog)
Em breve, migraremos e mesclaremos a documentação dos portais do Power Apps com a documentação do Power Pages.

Você pode usar operações disponíveis de API Web em portais. As operações da API Web consistem em solicitações e respostas HTTP. Este artigo fornece exemplos de operações de leitura, métodos, URI e o JSON de amostra que podem ser usados na solicitação HTTP.

Pré-requisitos

Sua versão do portal deve ser a 9.4.1.x ou superior.
Habilite a tabela e o campo para operações da API Web. Mais informações: Configurações do site para a API Web
A API Web de portais acessa registros da tabela e segue as permissões da tabela fornecidas a usuários por meio das funções Web associadas. Certifique-se de configurar as permissões de tabela corretas. Mais informações: Criar funções Web

Observação

Ao fazer referência a tabelas do Dataverse usando a API Web dos portais, você precisa usar EntitySetName, por exemplo, para acessar a tabela de conta, a sintaxe do código usará EntitySetName de contas.

Consultar registros

O seguinte exemplo consulta registros da conta:

Operação	Método	URI
Recuperar registros de tabela	GET	`[Portal URI]/_api/accounts` Exemplo: `https://contoso.powerappsportals.com/_api/accounts`

Resposta de amostra

{
"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 opções de consulta do sistema $ select e $top para retornar a propriedade do nome para as três primeiras contas:

Operação	Método	URI
Recupere os três primeiros registros de entidade	GET	`[Portal URI]/_api/accounts?$select=name,revenue&$top=3` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?$select=name,revenue&$top=3`

Recupere a conta usando a ID da conta:

Operação	Método	URI
Recuperar propriedade específica para um registro	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 amostra

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

Aplicar opções de consulta do sistema

Cada uma das opções de consulta do sistema anexada à URL para o conjunto de entidades é adicionada usando a sintaxe para cadeias de caracteres de consulta. A primeira é anexada após [?] e as seguintes opções de consulta são separadas usando [&]. Todas as opções de consulta diferenciam maiúsculas de minúsculas, conforme mostrado 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`

Propriedades da solicitação específica

Use a opção de consulta do sistema $select para limitar as propriedades retornadas, conforme mostrado 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

Esta é uma práticas recomendada de desempenho. Se as propriedades não forem especificadas e você tiver definido a configuração do site Webapi/<table name>/fields como *, todas as propriedades serão retornadas usando $select. Se nenhuma propriedade for especificada, um erro será retornado.

Filtrar resultados

Use a opção de consulta do sistema $filter para definir critérios para os quais as linhas serão retornadas.

Operadores de filtro padrão

A API Web é compatível com os operadores de filtro OData padrão listados na seguinte tabela:

Operador	Descrição	Exemplo
Operadores de comparação
eq	Igual a	$filter=revenue eq 100000
ne	Not Equal	$filter=revenue ne 100000
gt	Maior que	$filter=revenue gt 100000
ge	Maior ou igual a	$filter=revenue ge 100000
lt	Menor que	$filter=revenue lt 100000
le	Menor ou igual a	$filter=revenue le 100000
Operadores lógicos:
and	and lógico	$filter=revenue lt 100000 and revenue gt 2000
or	or lógico	$filter=contains(name,'(sample)') or contains(name,'test')
not	Negação lógica	$filter=not contains(name,'sample')
Operadores de agrupamento
( )	Agrupamento de precedência	(contains(name,'sample') ou contains(name,'test')) e revenue gt 5000

Funções de consulta padrão

A API Web é compatível com estas funções de consulta de cadeia de caracteres do OData padrão:

Função	Exemplo
contém	$filter=contains(name,'(sample)')
endswith	$filter=endswith(name,'Inc.')
startswith	$filter=startswith(name,'a')

Funções de consulta do Dataverse

A API da Web oferece suporte às funções de consulta do Dataverse para filtrar resultados. Para obter mais informações, consulte Referência da API Web de função de consulta.

Ordenar resultados

Especifique a ordem em que os itens são devolvidos usando a opção de consulta do sistema $orderby. Use o sufixo asc ou desc para especificar a ordem crescente ou decrescente, respectivamente. O padrão será ascendente se o sufixo não for aplicado. O exemplo a seguir mostra a recuperação do nome e das propriedades de receita de contas ordenadas por receita crescente e por nome decrescente.

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 resultados

Usando $apply , você pode agregar e agrupar seus dados dinamicamente, conforme visto nestes exemplos:

Cenários	Exemplo
Lista de status únicos na consulta	accounts?$apply=groupby((statuscode))
Soma agregada do valor estimado	opportunities?$apply=aggregate(estimatedvalue com soma como total)
Tamanho médio do negócio com base no valor estimado e status	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue com média como averagevalue)
Soma do valor estimado com base no status	opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue com soma como total))
Receita total da oportunidade por nome da conta	opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue com soma como total))
Nomes de contato principal para contas em 'WA'	accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data e hora de criação do último registro	accounts?$apply=aggregate(createdon com máximo como lastCreate)
Data e hora da primeira criação do registro	accounts?$apply=aggregate(createdon com mín. como firstCreate)

Recupere uma contagem de linhas

Use a opção de consulta do sistema $count com um valor verdadeiro para incluir uma contagem de entidades que correspondem aos critérios de filtro até 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 amostra

{
"@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 você não quiser retornar dados, exceto para a contagem, poderá aplicar $count a qualquer coleção para obter apenas o valor.

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

Resposta de amostra

3

Comparação de coluna

O seguinte exemplo mostra como comparar colunas 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`

Recupere os registros da tabela relacionada com uma consulta

Use a opção de consulta do sistema $expand nas propriedades de navegação para controlar quais dados de entidades relacionadas são retornados.

Propriedade de navegação associada à pesquisa

Você precisará usar a propriedade Microsoft.Dynamics.CRM.associatednavigationproperty como o atributo de pesquisa ao usar a opção de consulta $expand.

Para determinar a Microsoft.Dynamics.CRM.associatednavigationproperty de um atributo, você pode fazer a seguinte solicitação http GET para a coluna usando a seguinte convenção de nomenclatura: _name_value.

No exemplo a seguir, podemos determinar a propriedade de navegação associada da coluna Contato Principal da tabela Conta especificando o nome da coluna primarycontactid ao formatar o nome na solicitação: _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 amostra

{
"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 na resposta que a propriedade de navegação associada é primarycontactid. A propriedade de navegação associada pode ser o nome lógico ou o nome do esquema da coluna de pesquisa dependendo de como a tabela foi criada.

Para mais informações, consulte Recuperar dados sobre propriedades de pesquisa.

Recupere os registros da tabela relacionada, expandindo as propriedades de navegação de valor único

O exemplo a seguir mostra como recuperar o contato para todos os registros da conta. Para os registros de contato relacionados, estamos apenas 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 amostra

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

Recupere as tabelas relacionadas, expandindo propriedades de navegação com valor de coleção

Se você expandir os parâmetros de navegação com valor de coleção para recuperar tabelas relacionadas para conjuntos de entidades, apenas um nível de profundidade será retornado se houver dados. Caso contrário, a coleção retornará uma matriz vazia.

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

Recupere as tabelas relacionadas, expandindo propriedades de navegação com valor único e valor de coleção

O exemplo a seguir demonstra como você pode expandir entidades relacionadas para conjuntos de entidades usando propriedades de navegação com valor único e com valor de coleção. Você precisará especificar o nome do relacionamento da tabela na sintaxe do 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)`

Próxima Etapa

Operações de gravação, atualização e exclusão de portais usando a API Web

Confira também

Visão geral da API Web de portais
Tutorial: usar a API Web do portal
Configurar permissões de coluna

Observação

Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)

A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).

Compartilhar via

Consultar dados usando portais API Web

Pré-requisitos

Consultar registros

Aplicar opções de consulta do sistema

Propriedades da solicitação específica

Filtrar resultados

Operadores de filtro padrão

Funções de consulta padrão

Funções de consulta do Dataverse

Ordenar resultados

Agregar e agrupar resultados

Recupere uma contagem de linhas

Comparação de coluna

Recupere os registros da tabela relacionada com uma consulta

Propriedade de navegação associada à pesquisa

Recupere os registros da tabela relacionada, expandindo as propriedades de navegação de valor único

Recupere as tabelas relacionadas, expandindo propriedades de navegação com valor de coleção

Recupere as tabelas relacionadas, expandindo propriedades de navegação com valor único e valor de coleção

Próxima Etapa

Confira também

Comentários

Recursos adicionais