Comentários

Consultar dados usando portais API Web

  • Artigo
  • 2 minutos para o fim da leitura

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

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

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 true 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

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

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

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)

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.

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