Consultar os dados através da API Web dos portais

Artigo
12/27/2024

Pode utilizar as operações da API Web disponíveis no Power Pages. 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 site 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	URL
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	URL
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	URL
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	URL
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	URL
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 sã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	URL
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	URL
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	URL
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	URL
GET	`[Portal URI]/_api/contacts?$select=firstname&$filter=firstname eq lastname` Exemplo: `https://contoso.powerappsportals.com/_api/contacts?$select=firstname&$filter=firstname eq lastname`

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.

Precisa de usar Microsoft.Dynamics.CRM.associatednavigationproperty como o atributo de procura ao usar 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	URL
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.

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	URL
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 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 devolve uma matriz vazia.

Method	URL
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 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. Precisa de especificar o nome da relação de tabela na sintaxe do seu código.

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

Consultar registos com o FetchXML

Passe a consulta FetchXml como um valor de cadeia codificado por URL para a coleção de conjuntos de entidades usando o parâmetro de consulta FetchXml.

Por exemplo, para obter dados do conjunto de entidades da conta, componha uma consulta FetchXml definindo o parâmetro de nome do elemento de entidade para a conta.

<fetch top='2'>
  <entity name='account'>
      <attribute name='name' />
  </entity>
</fetch>

A cadeia de carateres codificada por URL para a consulta anterior é:

%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E

Method	URL
GET	`[Portal URI]/_api/accounts?fetchxml` Exemplo: `https://contoso.powerappsportals.com/_api/accounts?fetchXml=%3Cfetch%20top%3D%275%27%3E%0D%0A%3Centity%20name%3D%27account%27%3E%0D%0A%3Cattribute%20name%3D%27name%27%2F%3E%0D%0A%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E`

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

Passo Seguinte

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

Partilhar via

Consultar os dados através da API Web dos portais

Pré-requisitos

Consultar registos

Aplicar opções de consulta do sistema

Propriedades específicas do pedido

Filtrar resultados

Operadores de filtros padrão

Funções de consulta padrão

Funções de consulta do Dataverse

Ordenar resultados

Resultados agregados e de agrupamento

Obter uma contagem de linhas

Comparação de colunas

Propriedade de navegação associada de procura

Consultar registos com o FetchXML

Passo Seguinte

Veja também

Comentários

Recursos adicionais

Partilhar via

Consultar os dados através da API Web dos portais

Pré-requisitos

Consultar registos

Aplicar opções de consulta do sistema

Propriedades específicas do pedido

Filtrar resultados

Operadores de filtros padrão

Funções de consulta padrão

Funções de consulta do Dataverse

Ordenar resultados

Resultados agregados e de agrupamento

Obter uma contagem de linhas

Comparação de colunas

Obter registos de tabelas relacionadas com uma consulta

Propriedade de navegação associada de procura

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

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

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

Consultar registos com o FetchXML

Passo Seguinte

Veja também

Comentários

Recursos adicionais