Exemplo de dados de consulta da API Web (PowerShell)

Este exemplo do PowerShell versão 7.4.0 demonstra como executar várias operações de consulta em linhas de tabela Microsoft Dataverse usando a API Web do Dataverse. Este exemplo implementa as operações do Dataverse e a saída do console detalhadas no Exemplo de Dados de Consulta da API Web.

Exibir este exemplo no Github

Este exemplo usa as funções auxiliares do PowerShell da API Web do Dataverse para gerenciar a autenticação e fornecer funções reutilizáveis para executar operações comuns. Esses scripts são referenciados usando o dot sourcing com as seguintes linhas:

. $PSScriptRoot\..\Core.ps1
. $PSScriptRoot\..\TableOperations.ps1
. $PSScriptRoot\..\CommonFunctions.ps1

Observação

Este exemplo deve funcionar com Windows, Linux e macOS, mas só foi testado em Windows.

Pré-requisitos

Antes de executar este exemplo, você deve ler estes artigos que explicam os conceitos e padrões usados por estes exemplos:

Esses artigos têm os mesmos pré-requisitos.

Instalar ou verificar se os seguintes estão instalados

Verificar a instalação

  1. Abra o Visual Studio Code.

  2. No menu Terminal, selecione Novo Terminal.

  3. No painel de navegação Visual Studio Code, selecione o ícone para a extensão do PowerShell.

  4. Copie e cole o seguinte script na janela do terminal Visual Studio Code:

    Write-Host 'PowerShell Version:'$PSVersionTable.PSVersion.ToString()
Write-Host 'PowerShell Az version:'(Get-InstalledModule Az).Version

  5. Pressione Enter. O resultado deve ser assim:

    PowerShell Version: 7.4.0
PowerShell Az version: 11.1.0

Se você não vir resultados como este, instale ou atualize os pré-requisitos.

Você também precisará

  • Uma conta de usuário válida para um ambiente do Dataverse
  • A URL para o ambiente do Dataverse ao qual você deseja se conectar. Veja Exibir recursos do desenvolvedor para saber como encontrá-lo. Parece algo assim: https://yourorg.crm.dynamics.com/, onde yourorg.crm é diferente.
  • Compreensão básica da linguagem de script do PowerShell

Como executar este exemplo

  1. Clone ou baixe o repositório PowerApps-Samples .

  2. Abra o arquivo QueryData.ps1 usando Visual Studio Code

  3. Edite esta linha para usar a URL do ambiente ao qual você deseja se conectar:

    Connect 'https://yourorg.crm.dynamics.com/' # change this

  4. (Opcional) Defina a $deleteCreatedRecords variável para $false se você não quiser excluir os registros que este exemplo cria.

  5. Pressione F5 para executar o exemplo.

  6. Na primeira vez que você executar o exemplo, uma janela do navegador será aberta. Na janela do navegador, insira ou selecione as credenciais que você deseja usar para autenticar.

Para se conectar como um usuário diferente, execute o comandoDisconnect-AzAccount e tente novamente.

Code

O código deste exemplo está em: PowerApps-Samples/dataverse/webapi/PS/QueryData/QueryData.ps1

Demonstrações

Este exemplo tem 11 regiões:

Seção 0: Criar registros para consultar

Operações: crie um registro de conta com registros de contato relacionados e cada contato tem registros de tarefas relacionados. Esses são os dados de exemplo usados em toda a demonstração.

Seção 1: Selecionando propriedades específicas

Operações:

  • Use $select a opção de consulta do sistema para recuperar propriedades específicas.
  • Inclua Prefer: odata.include-annotations="*" cabeçalho para obter valores formatados.

Seção 2: Usando funções de consulta

Operações:

  • Use funções de consulta padrão, como contains, endswithe startswith para filtrar resultados.
  • Use funções de consulta específicas do Dataverse, como LastXHours, Last7Days, , TodayBetweene In.
  • Use operadores de filtro e operadores lógicos (eq, , ne, gt, and, or).
  • Defina a precedência usando parênteses em expressões de filtro.

Seção 3: Ordenação e apelidos

Operações:

  • Use $orderby para classificar os resultados da consulta.
  • Use aliases parametrizados com $filter e $orderby para simplificar consultas.

Seção 4: Limitar e contar resultados

Operações:

  • Use $top para limitar o número de resultados retornados.
  • Use $count para obter a contagem total de registros correspondentes à consulta.

Seção 5: Paginação

Operações:

  • Use o Prefer: odata.maxpagesize cabeçalho da solicitação para controlar o tamanho da página.
  • Use a anotação @odata.nextLink para recuperar páginas subsequentes de resultados.

Seção 6: Expandindo resultados

Operações:

  • Use $expand com propriedades de navegação com valor único para incluir registros relacionados.
  • Use $expand com propriedades de navegação de valor de coleção de expansão.
  • Use $expand com várias propriedades de navegação em uma única solicitação.
  • Use $expand aninhado para recuperar vários níveis de registros relacionados.

Seção 7: Resultados agregados

Operações: use $apply=aggregate com funções como average, sume minmax para calcular valores agregados.

Seção 8: Consultas FetchXML

Operações:

  • Enviar solicitações usando FetchXML com o parâmetro de string de consulta fetchXml.
  • Use paginação com FetchXML usando os atributos page e count.

Seção 9: Usando consultas predefinidas

Operações:

  • Execute uma consulta salva (vista do sistema) usando savedQuery parâmetro.
  • Execute uma consulta de usuário (modo de exibição salvo) usando o parâmetro userQuery.

Seção 10: Excluir registros de exemplo

Operações: uma referência a cada registro criado neste exemplo foi adicionada a uma lista à medida que foi criada. Esta seção percorre essa lista e exclui cada registro.

Limpeza

Por padrão, este exemplo exclui todos os registros criados nele. Se você quiser exibir os registros criados após a conclusão do exemplo, altere a deleteCreatedRecords variável false para e você será solicitado a decidir se deseja excluir os registros.

Consulte também

Utilizar a API Web do Dataverse
Consultar dados usando a API Web
Quick Start Web API com o PowerShell e Visual Studio Code
Usar o PowerShell e o Visual Studio Code com a API Web do Dataverse
Exemplos de API Web
Exemplo de dados de consulta da API Web
Exemplo de Dados de Consulta da API Web (C#)
Exemplo de dados de consulta da API Web (JavaScript do lado do cliente)

  • Last updated on