Partilhar via

Consultar os dados através da API Web dos portais

  • Artigo

Nota

A partir de 12 de outubro de 2022, os portais do Power Apps passam a ser Power Pages. Mais informações: O Microsoft Power Pages está agora em disponibilidade geral (blogue)
Em breve, vamos migrar e unir a documentação dos portais do Power Apps com a documentação do Power Pages.

Pode utilizar as operações da API Web disponíveis nos portais. As operações API Web consistem em pedidos e respostas HTTP. Este artigo fornece operações de leitura de amostras, métodos, URI e o JSON de amostra que pode utilizar no pedido HTTP.

Pré-requisitos

  • A sua versão do portal tem de ser 9.4.1.x ou superior.

  • Ative a tabela e o campo para as operações da API Web. Mais informações: Definições do site para a API Web

  • A API Web dos portais acede aos registos de tabelas e segue as permissões de tabela dadas aos utilizadores através das funções Web associadas. Certifique-se de que configura as permissões de tabela corretas. Mais informações: Criar funções Web

Nota

Quando se refere a tabelas do Dataverse que utilizam a API Web de portais, precisa de utilizar o EntitySetName, por exemplo, para aceder à tabela de conta, a sintaxe do código irá utilizar o EntitySetName de contas.

Consultar registos

O seguinte exemplo consulta os registos de contas:

Operação Method URI
Obter registos 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"
    }
]
}

Utilize as opções de consulta de sistema $select e $top para devolver a propriedade do nome para as três primeiras contas:

Operação Method URI
Obter os três primeiros registos de entidades GET [Portal URI]/_api/accounts?$select=name,revenue&$top=3

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

Obter a conta através do ID da conta:

Operação Method URI
Obter a propriedade específica para um registo 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 que anexar ao URL para o conjunto de entidades é adicionada através da sintaxe para as cadeias de consulta. A primeira é acrescentada após [?] e as seguintes opções de consulta são separadas por [&]. Todas as opções de consulta são sensíveis às maiúsculas e minúsculas, como é mostrado no seguinte exemplo:

Method 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 específicas do pedido

Utilize a opção de consulta do sistema $select para limitar as propriedades devolvidas, como é mostrado no seguinte exemplo:

Method 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 melhor prática de desempenho. Se as propriedades não forem especificadas e tiver configurado o valor de definição do site Webapi/<table name>/fields para * e, em seguida, todas as propriedades serão devolvidas através de $select. Se não forem especificadas propriedades, será devolvido um erro.

Filtrar resultados

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

Operadores de filtros padrão

A API Web suporta os operadores de filtro OData padrão listados na seguinte tabela:

Operator Descrição Exemplo
Operadores de Comparação
eq Igual a $filter=revenue eq 100000
ne Não é Igual a $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 E lógico $filter=revenue lt 100000 e revenue gt 2000
or OU lógico $filter=contains(name,'(sample)') ou 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 suporta estas funções de consulta da cadeia 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 Web suporta funções de consulta do Dataverse para filtrar resultados. Para obter mais informações, consulte Referência de Funções de Consulta da API Web.

Ordenar resultados

Especifique a ordem pela qual os itens são devolvidos através da opção de consulta do sistema $orderby . Utilize o sufixo asc ou desc para especificar a ordem crescente ou decrescente, respetivamente. A predefinição é crescente se o sufixo não for aplicado. O exemplo a seguir mostra a obtenção das propriedades de nome e de receitas das contas ordenadas por receitas crescentes e pelo nome decrescente.

Method 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

Resultados agregados e de agrupamento

Ao utilizar  $apply , poderá agregar e agrupar os seus dados de forma dinâmica, tal como é visto nos seguinte exemplos:

Cenários Exemplo
Lista de estatutos exclusivos na consulta accounts?$apply=groupby((statuscode))
Soma agregada do valor estimado opportunities?$apply=aggregate(estimatedvalue com a soma como total)
Tamanho médio do negócio baseado no valor estimado e no estado opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue com a média como averagevalue)
Soma do valor estimado com base no estado opportunities?$apply=groupby((statuscode),aggregate(estimatedvalue com a soma como total))
Receita total da oportunidade por nome de conta opportunities?$apply=groupby((parentaccountid/name),aggregate(estimatedvalue com a soma como total))
Nomes de contacto principal para as contas em "WA" accounts?$apply=filter(address1_stateorprovince eq 'WA')/groupby((primarycontactid/fullname))
Data e hora do registo criado pela última vez accounts?$apply=aggregate(createdon com max como lastCreate)
Data e hora do registo criado pela primeira vez accounts?$apply=aggregate(createdon com min como firstCreate)

Obter uma contagem de linhas

Utilize a opção de consulta do sistema $count com um valor de true para incluir uma contagem de entidades que corresponde aos critérios de filtro até 5.000.

Method 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 não quiser devolver quaisquer dados, exceto para a contagem, pode aplicar $count a qualquer coleção para obter apenas o valor.

Method URI
GET [Portal URI/_api/accounts/$count

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

Resposta de amostra

3

Comparação de colunas

O exemplo seguinte mostra como comparar as colunas através da API Web:

Method 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

Obter registos de tabelas relacionadas com uma consulta

Utilize a opção de consulta do sistema $expand nas propriedades de navegação para controlar que dados das entidades relacionadas que são devolvidos.

Propriedade de navegação associada de procura

Terá de utilizar a Microsoft.Dynamics.CRM.associatednavigationproperty como o atributo de procura ao utilizar a opção de consulta $expand.

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

No exemplo que se segue, podemos determinar a propriedade de navegação associada da coluna Contacto Principal da tabela Conta especificando o nome da coluna primarycontactid ao formatar o nome no pedido: _primarycontactid_value.

Method 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 pela resposta que a propriedade de navegação associada é primarycontactid. A propriedade de navegação associada pode ser o nome lógico ou o nome de esquema da coluna de procura, consoante a forma como a tabela foi criada.

Para mais informações, consulte Obter dados sobre propriedades de procura.

Obter os registos de tabelas relacionadas ao expandir as propriedades de navegação de valor único

O exemplo a seguir mostra como obter o contacto para todos os registos de conta. Para os registos de contacto relacionados, estamos apenas a obter o contactid e o fullname.

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

Obter as tabelas relacionadas ao expandir as propriedades de navegação com valor de coleção

Se expandir os parâmetros de navegação com valor de coleção para obter as tabelas relacionadas para os conjuntos de entidades, apenas um nível de profundidade é devolvido se existirem dados. Caso contrário, a coleção devolverá uma matriz vazia.

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

Obter as tabelas relacionadas ao expandir as propriedades de navegação tanto de valor único como com valor de coleção

O exemplo seguinte demonstra como pode expandir as entidades relacionadas para os conjuntos de entidades através das propriedades de navegação tanto de valor único como com valor de coleção. Terá de especificar o nome de relação da tabela na sintaxe do seu código.

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

Passo Seguinte

Operações de escrita, atualização e eliminação de portais com a API Web

Consulte também

Descrição geral de API Web de portais
Tutorial: Utilizar a API Web de portais
Configurar permissões de coluna

Nota

Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)

O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).