Microsoft Dataverse
Consultar e administrar registros em tabelas do Microsoft Dataverse.
O que faz
Integre o Microsoft Dataverse ao seu fluxo. Crie, leia, atualize, exclua, faça upsert, associe, consulte, busque e execute ações e funções nas tabelas do Dataverse usando a Web API. Suporta operações em lote, FetchXML, envio de arquivos, busca por relevância e consulta de metadados de tabelas. Funciona com Dynamics 365, Power Platform e ambientes personalizados do Dataverse.
Quando usar: Use quando o seu fluxo precisar consultar e administrar registros em tabelas do Microsoft Dataverse.
Exemplo de situação: Localizar um cadastro e aproveitar seus dados nas etapas seguintes.
Antes de começar
Conexão necessária: OAuth.
Conecte a conta pelo botão de autorização do campo de credencial e confira qual usuário ou organização foi escolhido.
Passo a passo
- Adicione Microsoft Dataverse ao desenho a partir da aba Blocos e ligue a entrada dele à etapa anterior.
- Conecte a conta pelo botão de autorização do campo de credencial e confira qual usuário ou organização foi escolhido.
- Escolha a operação. O painel mostra só os campos que essa operação usa.
- Preencha os campos obrigatórios. Para usar um dado de uma etapa anterior, digite < e escolha o bloco e o campo.
- Clique em Executar com dados de teste e confira, no terminal, o que entrou e o que saiu do bloco.
- Só publique depois de conferir o resultado da execução de teste.
Operações
| Operação | O que faz |
|---|---|
| Listar registros | Lista registros com o bloco Microsoft Dataverse. |
| Consultar registro | Consulta registro com o bloco Microsoft Dataverse. |
| Criar registro | Cria registro com o bloco Microsoft Dataverse. |
| Atualizar registro | Atualiza registro com o bloco Microsoft Dataverse. |
| Criar ou atualizar registro | Cria ou atualizar registro com o bloco Microsoft Dataverse. |
| Excluir registro | Exclui registro com o bloco Microsoft Dataverse. |
| Criar vários | Cria vários com o bloco Microsoft Dataverse. |
| Atualizar vários | Atualiza vários com o bloco Microsoft Dataverse. |
| Consulta FetchXML | Executa a operação “Consulta FetchXML” com o bloco Microsoft Dataverse. |
| Buscar | Busca com o bloco Microsoft Dataverse. |
| Executar ação | Executa ação com o bloco Microsoft Dataverse. |
| Executar função | Executa função com o bloco Microsoft Dataverse. |
| Enviar arquivo | Envia arquivo com o bloco Microsoft Dataverse. |
| Baixar arquivo | Baixa arquivo com o bloco Microsoft Dataverse. |
| Associar registros | Associa registros com o bloco Microsoft Dataverse. |
| Desassociar registros | Desassocia registros com o bloco Microsoft Dataverse. |
| Consultar usuário conectado (WhoAmI) | Consulta usuário conectado (WhoAmI) com o bloco Microsoft Dataverse. |
Campos
Operação
Escolhe qual ação este bloco executará.
- Opções:
- Listar registros · Consultar registro · Criar registro · Atualizar registro · Criar ou atualizar registro · Excluir registro · Criar vários · Atualizar vários · Consulta FetchXML · Buscar · Executar ação · Executar função · Enviar arquivo · Baixar arquivo · Associar registros · Desassociar registros · Consultar usuário conectado (WhoAmI)
- Padrão:
- Listar registros
Conta da Microsoft
ObrigatórioSeleciona a conta já conectada que autoriza o acesso ao serviço.
- Exemplo:
- (escolha a conta conectada)
URL do ambiente
ObrigatórioInforma o endereço seguro do serviço ou recurso que será acessado.
- Exemplo:
- https://api.exemplo.com/v1/recurso
Nome do conjunto de entidades
Obrigatório conforme a operaçãoNome da tabela no plural (ex.: accounts, contacts).
- Quando aparece:
- Quando o campo “Operação” for diferente de “Consultar usuário conectado (WhoAmI)” ou “Buscar”
- Exemplo:
- Exemplo de atendimento
ID do registro
Obrigatório conforme a operaçãoGUID do registro (ex.: 00000000-0000-0000-0000-000000000000).
- Aparece em:
- Consultar registro, Atualizar registro, Criar ou atualizar registro, Excluir registro, Associar registros, Desassociar registros, Enviar arquivo, Baixar arquivo, Executar ação, Executar função
- Exemplo:
- id-do-recurso
Dados do registro
Obrigatório conforme a operaçãoObjeto JSON com os valores do registro, usando os nomes lógicos das colunas do Dataverse (ex.: name para o nome da conta e telephone1 para o telefone).
- Aparece em:
- Criar registro, Atualizar registro, Criar ou atualizar registro
- Exemplo:
- {"name": "Contoso", "telephone1": "555-0100"}
FetchXML
Obrigatório conforme a operaçãoConsulta em FetchXML, o formato XML de consultas do Dataverse, indicando a tabela, as colunas e os filtros; útil para junções e agrupamentos que a listagem comum não cobre.
- Aparece em:
- Consulta FetchXML
- Exemplo:
- <fetch top="50"><entity name="account"><attribute name="name"/><filter><condition attribute="statecode" operator="eq" value="0"/></filter><…
Termo de busca
Obrigatório conforme a operaçãoTexto da busca (ex.: Contoso).
- Aparece em:
- Buscar
- Exemplo:
- Contoso
Entidades da busca
Em campos adicionaisDefine a consulta ou o filtro aplicado aos dados.
- Aparece em:
- Buscar
- Exemplo:
- [{"Name":"account","SelectColumns":["name"],"SearchColumns":["name"]}]
Modo de busca
Em campos adicionaisDefine a consulta ou o filtro aplicado aos dados.
- Aparece em:
- Buscar
- Opções:
- Qualquer (corresponde a qualquer termo) · Todos (corresponde a todos os termos)
- Padrão:
- Qualquer (corresponde a qualquer termo)
Tipo de consulta
Em campos adicionaisDefine a consulta ou o filtro aplicado aos dados.
- Aparece em:
- Buscar
- Opções:
- Simples (padrão) · Lucene (regex, aproximada, por proximidade)
- Padrão:
- Simples (padrão)
Facetas
Em campos adicionaisLista em JSON das facetas da busca, que agrupam e contam os resultados por um campo (ex.: ["entityname,count:100"] conta os resultados por tabela).
- Aparece em:
- Buscar
- Exemplo:
- ["entityname,count:100"]
Pular
Em campos adicionaisQuantidade de resultados a pular na paginação.
- Aparece em:
- Buscar
- Exemplo:
- Quantidade de resultados a pular na paginação
Nome da ação
Obrigatório conforme a operaçãoDefine o nome ou título usado para identificar o recurso.
- Aparece em:
- Executar ação
- Exemplo:
- Exemplo de atendimento
Nome da função
Obrigatório conforme a operaçãoDefine o nome ou título usado para identificar o recurso.
- Aparece em:
- Executar função
- Exemplo:
- Exemplo de atendimento
Parâmetros da função
Em campos adicionaisParâmetros passados à função do Dataverse, no formato nome=valor separados por vírgula e com textos entre aspas simples (ex.: LocalizedStandardName='E. South America Standard Time',LocaleId=1046).
- Aparece em:
- Executar função
- Exemplo:
- LocalizedStandardName='Pacific Standard Time',LocaleId=1033
Parâmetros da ação
Objeto JSON com os parâmetros que a ação do Dataverse exige, com os nomes definidos na própria ação (ex.: Target com a conta a ser processada).
- Aparece em:
- Executar ação
- Exemplo:
- {"Target": {"@odata.type": "Microsoft.Dynamics.CRM.account", "accountid": "..."}}
Nome lógico da tabela
Obrigatório conforme a operaçãoNome da tabela no singular (ex.: account, contact).
- Aparece em:
- Criar vários, Atualizar vários
- Exemplo:
- Exemplo de atendimento
Registros
Obrigatório conforme a operaçãoInforma uma estrutura JSON com os dados exigidos por esta operação.
- Aparece em:
- Criar vários, Atualizar vários
- Exemplo:
- { "chave": "valor" }
Coluna de arquivo
Obrigatório conforme a operaçãoNome lógico da coluna de arquivo (ex.: entityimage, cr_document).
- Aparece em:
- Enviar arquivo, Baixar arquivo
- Exemplo:
- entityimage, cr_document
Nome do arquivo
Obrigatório conforme a operaçãoInforma ou seleciona o arquivo usado nesta operação.
- Aparece em:
- Enviar arquivo
- Exemplo:
- Exemplo de atendimento
Arquivo
Obrigatório conforme a operaçãoEnvie um arquivo.
- Aparece em:
- Enviar arquivo
- Exemplo:
- (selecione um arquivo de teste)
Arquivo
Obrigatório conforme a operaçãoEm campos adicionaisReferencie um arquivo de blocos anteriores (ex.: {{block_1.output.file}}).
- Aparece em:
- Enviar arquivo
- Exemplo:
- {{block_1.output.file}}
Colunas a retornar
Em campos adicionaisColunas separadas por vírgula (ex.: name,telephone1,emailaddress1).
- Aparece em:
- Listar registros, Consultar registro
- Exemplo:
- name,telephone1,emailaddress1
Filtro
Filtro OData (ex.: statecode eq 0 and contains(name,'Contoso')).
- Aparece em:
- Listar registros, Buscar
- Exemplo:
- status = 'ativo'
Ordenar por
Em campos adicionaisOrdem dos registros devolvidos: nome lógico da coluna seguido de asc (crescente) ou desc (decrescente), separando várias colunas por vírgula (ex.: createdon desc).
- Aparece em:
- Listar registros, Buscar
- Exemplo:
- name asc, createdon desc
Máximo de resultados
Em campos adicionaisQuantidade máxima de registros a retornar.
- Aparece em:
- Listar registros, Buscar
- Exemplo:
- Quantidade máxima de registros a retornar
Incluir contagem total
Em campos adicionaisDefine se este comportamento fica ativado ou desativado.
- Aparece em:
- Listar registros
- Opções:
- Não · Sim
- Padrão:
- Não
Expandir
Em campos adicionaisPropriedades de navegação a expandir (ex.: primarycontactid).
- Aparece em:
- Listar registros, Consultar registro
- Exemplo:
- primarycontactid
Propriedade de navegação
Obrigatório conforme a operaçãoNome do relacionamento do Dataverse que liga os dois registros, chamado de propriedade de navegação (ex.: contact_customer_accounts).
- Aparece em:
- Associar registros, Desassociar registros
- Exemplo:
- contact_customer_accounts
Tipo de navegação
Em campos adicionaisEscolhe uma das opções aceitas por este campo.
- Aparece em:
- Associar registros
- Opções:
- Coleção (padrão) · Valor único (lookup)
- Padrão:
- Coleção (padrão)
Conjunto de entidades de destino
Obrigatório conforme a operaçãoNome da tabela de destino (ex.: contacts).
- Aparece em:
- Associar registros
- Exemplo:
- Exemplo de atendimento
ID do registro de destino
Obrigatório conforme a operaçãoGUID do registro de destino.
- Aparece em:
- Associar registros, Desassociar registros
- Exemplo:
- id-do-recurso
Saídas
Para usar um resultado deste bloco em uma etapa seguinte, digite < no campo e escolha o bloco e o campo. A referência tem o formato <microsoftdataverse.records>: antes do ponto vai o nome do bloco no seu fluxo, em minúsculas, sem espaços e sem acentos.
| Referência | Tipo | O que contém |
|---|---|---|
<microsoftdataverse.records> | json | Lista de registros (listar/fetchxml/busca). |
<microsoftdataverse.record> | json | Dados de um único registro. |
<microsoftdataverse.recordId> | string | ID do registro. |
<microsoftdataverse.count> | number | Quantidade de registros retornados na página atual. |
<microsoftdataverse.totalCount> | number | Total de registros correspondentes no servidor. |
<microsoftdataverse.nextLink> | string | URL da próxima página de resultados. |
<microsoftdataverse.created> | boolean | Indica se um novo registro foi criado (upsert). |
<microsoftdataverse.userId> | string | ID do usuário autenticado (WhoAmI). |
<microsoftdataverse.businessUnitId> | string | ID da unidade de negócios (WhoAmI). |
<microsoftdataverse.organizationId> | string | ID da organização (WhoAmI). |
<microsoftdataverse.entitySetName> | string | Nome do conjunto de entidades de origem (associar/desassociar) ou nome do conjunto de entidades consultado (metadados da tabela). |
<microsoftdataverse.navigationProperty> | string | Propriedade de navegação usada (associar/desassociar). |
<microsoftdataverse.targetEntitySetName> | string | Nome do conjunto de entidades de destino (associar). |
<microsoftdataverse.targetRecordId> | string | GUID do registro de destino (associar/desassociar). |
<microsoftdataverse.success> | boolean | Indica se a operação foi concluída com sucesso. |
<microsoftdataverse.result> | json | Dados do resultado da ação/função. |
<microsoftdataverse.ids> | json | Lista de IDs dos registros criados (criar vários). |
<microsoftdataverse.fetchXmlPagingCookie> | string | Cookie de paginação do FetchXML. |
<microsoftdataverse.moreRecords> | boolean | Indica se há mais registros disponíveis (FetchXML). |
<microsoftdataverse.results> | json | Lista de resultados da busca. |
<microsoftdataverse.facets> | json | Resultados das facetas da busca (quando há facetas pedidas). |
<microsoftdataverse.file> | file | Arquivo baixado, guardado nos arquivos da execução. |
<microsoftdataverse.fileContent> | string | Conteúdo do arquivo baixado, codificado em Base64. |
<microsoftdataverse.fileName> | string | Nome do arquivo enviado ou baixado. |
<microsoftdataverse.fileSize> | number | Tamanho do arquivo em bytes. |
<microsoftdataverse.mimeType> | string | Tipo MIME do arquivo. |
<microsoftdataverse.fileColumn> | string | Nome lógico da coluna de arquivo para onde o arquivo foi enviado ou de onde foi baixado. |
<microsoftdataverse.logicalName> | string | Nome lógico da tabela no singular (metadados da tabela). |
<microsoftdataverse.displayName> | string | Nome de exibição traduzido da tabela (metadados da tabela). |
<microsoftdataverse.primaryIdAttribute> | string | Nome lógico da coluna de chave primária (metadados da tabela). |
<microsoftdataverse.primaryNameAttribute> | string | Nome lógico da coluna de nome principal (metadados da tabela). |
<microsoftdataverse.attributes> | json | Definições das colunas da tabela (metadados da tabela). |
<microsoftdataverse.metadata> | json | Resposta bruta completa dos metadados da tabela (metadados da tabela). |
Exemplo de uso
Objetivo: Localizar um cadastro e aproveitar seus dados nas etapas seguintes.
- Operação
- Listar registros
- Conta da Microsoft
- (escolha a conta conectada)
- URL do ambiente
- https://api.exemplo.com/v1/recurso
- Nome do conjunto de entidades
- Exemplo de atendimento
- Filtro
- status = 'ativo'
Os valores são ilustrativos. Teste primeiro com dados fictícios ou de homologação.
Erros comuns e como resolver
- O bloco não executa
- Confira se existe um caminho de setas que parte do gatilho (ou do Início) até este bloco. Blocos soltos no desenho são ignorados.
- Aparece “Validação do fluxo” no terminal
- Há campo obrigatório vazio. Clique no aviso, abra o bloco indicado e preencha o campo marcado.
- Um campo chega vazio na etapa seguinte
- Confira se a referência aponta para um bloco que já executou e para um campo que existe, como <microsoftdataverse.records>. O nome antes do ponto é o nome do bloco no seu fluxo, em minúsculas, sem espaços e sem acentos.
- O campo que eu procuro não aparece
- Os campos mudam conforme a operação escolhida. Escolha a operação primeiro; campos menos usados ficam em “Mostrar campos adicionais”.
- Erro de autorização ou permissão (401/403)
- A conta conectada perdeu o acesso ou não tem permissão para esta operação. Reconecte a conta no campo de credencial e confirme as permissões pedidas.
- Não foi possível conectar ao banco
- Confira endereço, porta, nome do banco e usuário da conexão, e se o banco aceita conexões vindas da plataforma (firewall e lista de IPs liberados).
- O serviço recusou a chamada ou devolveu erro
- Leia a mensagem no terminal: ela traz o motivo informado pelo serviço. Confira IDs, limites de uso e permissões, e teste antes com um recurso de homologação.
Blocos relacionados
- Amazon DynamoDBConsultar, inserir, varrer, atualizar e excluir itens em tabelas do Amazon DynamoDB.
- Amazon RDSConsultar e alterar bancos Amazon RDS compatíveis por meio da Data API.
- ClickHouseConsultar e alterar dados em um banco ClickHouse.
- DatabricksExecutar consultas SQL e administrar trabalhos no Databricks.
- ElasticsearchPesquisar, indexar e administrar dados no Elasticsearch.
- Google AppSheetConsultar, adicionar, editar e excluir linhas de uma tabela do Google AppSheet.