Introdução às entidades no Microsoft Dynamics 365

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

As entidades são usadas para modelar e gerenciar dados corporativos no Microsoft Dynamics 365. Por exemplo, entidades como conta, campanha e incidente (ocorrência) podem ser usadas para rastrear e suportar vendas, marketing e atividades de serviço. Uma entidade tem um conjunto de atributos e cada atributo representa um item de dados de um determinado tipo. Por exemplo, a entidade da conta tem os atributos Name, Address e OwnerId. Conceitualmente, uma entidade é como uma tabela do banco de dados e os atributos da entidade correspondem às colunas da tabela. Criar um registro de entidade (ou somente um registro) no Microsoft Dynamics 365 é como adicionar uma linha a uma tabela do banco de dados. As entidades são divididas em três categorias: sistema, negócios e personalizado. Como um desenvolvedor trabalhando com dados corporativos, você usará entidades comerciais e personalizadas. As entidades do sistema são usadas pelo Microsoft Dynamics 365 para lidar com todos os processos internos, como fluxos de trabalho e trabalhos assíncronos. Não é possível excluir ou personalizar entidades do sistema.

As entidades corporativas fazem parte da instalação padrão do Microsoft Dynamics 365 e aparecem na interface do usuário de personalização. Uma conta, um contato e uma carta são exemplos de entidades corporativas. Após a instalação, é possível adicionar entidades personalizadas ao Microsoft Dynamics 365 para abordar necessidades comerciais específicas da organização. Em uma Microsoft Dynamics 365Solução, você pode definir entidades e atributos corporativas e personalizadas e podem ser personalizáveis ou não. É possível alterar uma entidade personalizável renomeando, adicionando novos atributos ou alterando várias configurações, como configurações de detecção de duplicatas ou suporte de fila. Não é possível modificar uma entidade não personalizável. Para obter mais informações sobre personalização, soluções não gerenciadas e gerenciadas e as propriedades gerenciadas, consulte Embalar e distribuir extensões usando soluções.

Se você estiver usando o modelo de agendamento de adiantado, uma entidade é representada por uma classe, como a classe Account que representa a entidade conta. Os atributos da entidade são representados por propriedades de classe. Esta classe é gerada pela ferramenta CrmSvcUtil. Para obter mais informações, consulte Use classes de entidade de limite antecipado no código. Como alternativa, é possível gravar programas que funcionam com os dados de entidade usando uma abordagem dinâmica. Para obter mais informações, consulte Usar a classe de entidade late bound no código.

Neste tópico

Metadados da entidade

Ações em registros de entidade

Propriedade da entidade

Estado e status do registro

Imagens de entidade

Metadados da entidade

Os metadados para uma organização Microsoft Dynamics 365 contém as definições das entidades, atributos e relacionamentos entre as entidades. Para obter mais informações, consulte Os metadados e os modelos de dados no Microsoft Dynamics 365. Como um desenvolvedor, há muitos casos em que é útil poder encontrar todos os metadados para uma organização. Existem várias maneiras de localizar e consultar os metadados:

• Você pode usar o navegador dos metadados da entidade para exibir entidades e suas propriedades no Microsoft Dynamics 365. Para obter detalhes, consulte Procurar os metadados da sua organização.

• O pacote SDK contém as mesmas informações em uma planilha do Microsoft Office Excel. É possível localizar no arquivo SDK\Tools\EntityMetadata.xlsx.

• Você pode gerar os metadados para sua organização usando esses exemplos:

  • Exemplo: Despejar metadados da entidade em um arquivo

  • Exemplo: despejar informações de privilégio de entidade em um arquivo

  • Exemplo: Despejar metadados do atributo em um arquivo

  • Exemplo: Informações de relacionamento de entidades de despejo para um arquivo

  • Exemplo: Informações de conjunto de opções globais de despejo para um arquivo

Você pode criar os seguintes tipos de relacionamentos entre entidades: um-para-muitos, muitos-para-um e muitos-para-muitos. Os registros para relações muitos-para-muitos são armazenados em uma entidade de interseção. Depois que um relacionamento é definido, use a mensagem AssociateRequest ou o método Associate para criar um link entre os registros especificados e use a mensagem DisassociateRequest ou o método Disassociate para remover um link entre os registros especificados.

Nas relações um-para-muitos ou muitos-para-um, algumas ações no registro da entidade primária afetam os registros da entidade secundária. As ações que têm um comportamento em cascata incluem: Atribuir, Excluir, Mesclar, Compartilhar, Descompartilhar e Reassociar. Para obter mais informações, consulte Comportamento do relacionamento entre entidades.

Os nomes usados nos metadados da entidade

As entidades, atributos e relacionamentos tem vários nomes diferentes. A tabela a seguir lista os vários nomes usados no metadados.

Ações em registros de entidade

Cada entidade oferece suporte a diversas ações, por exemplo, criar ou excluir um registro ou atribuir um registro a outro usuário ou equipe. Nem todas as ações são permitidas em todos os tipos de entidade ou atributos. Para cada atributo, os metadados definem se uma determinada ação terá suporte. Por exemplo, as propriedades de um atributo, como IsValidForCreate, IsValidForRead e IsValidForUpdate informam se você pode criar, recuperar ou atualizar o atributo.Para obter mais informações:Operações válidas em atributos.

Para executar uma ação, você chama um dos métodos no IOrganizationService. Por exemplo, para criar um registro no Microsoft Dynamics 365, você pode usar o método IOrganizationService.Create ou IOrganizationService.Execute com a mensagem CreateRequest correspondente. É necessário ter os privilégios e direitos de acesso necessários para executar essas ações. Para obter mais informações, consulte O modelo de segurança do Microsoft Dynamics 365.

A tabela a seguir lista as ações que são permitidas nos registros de entidade personalizado e de negócios e os métodos e as mensagens que você pode usar para executar essas ações.

Criar

Para executar esta ação, o chamador deve ter Create message privileges. Os direitos de acesso não se aplicam à ação Criar, mas se aplicam ao registro depois de criada.

Para ser proprietário de um registro ou recuperar o registro recém-criado, um usuário ou uma equipe também deve ter privilégios de leitura e direitos de acesso no novo registro. Por exemplo, se você tiver os privilégios para criar contas, é possível criar um registro de conta e atribuir a outro usuário ou equipe. Entretanto, se você também tem o privilégio de leitura para contas e direitos de acesso no novo registro, não é possível criar uma conta e ser o proprietário dessa nova conta.

Atualização

Para realizar esta ação, o chamador deve ter Update message privileges e direitos de acesso nos registros de entidade que serão atualizados.

Quando você atualiza um registro, somente os atributos que você especifica dados ou para o qual você tenha especificado nulo são atualizados. Todos os valores permanecem o mesmo. Além disso, se você especificar os dados para atributos que não são válidos para atualização, eles são ignorados.

Excluir

Para realizar esta ação, o chamador deve ter Delete message privileges e direitos de acesso nos registros de entidade sendo excluídos.

As regras em cascata determinam se os registros relacionados serão excluídos ao mesmo tempo. Para obter mais informações, consulte Comportamento do relacionamento entre entidades.

Normalmente, você só deve excluir registros inseridos por engano. No caso de alguns tipos de registros, você pode desativar ou fechar o registro em vez de excluir. Nem todos os tipos de registros podem ser excluídos.

Recuperar

Para realizar esta ação, o chamador deve ter Retrieve message privileges e direitos de acesso nos registros de entidade recuperados.

Recuperar vários

Para realizar esta ação, o chamador deve ter Retrieve message privileges e direitos de acesso nos registros de entidade recuperados.

Para recuperar uma coleção de registros com base em parâmetros da consulta, você pode usar uma expressão de consulta ou linguagem de consulta FetchXML. As expressões de consulta permitem criar uma árvore de consulta usando uma hierarquia de classes. Os métodos que usam uma expressão de consulta retornam um conjunto de registros digitados. O FetchXML permite criar uma consulta usando uma linguagem XML. O FetchXML retorna uma cadeia de caracteres XML. Portanto, é necessário fazer mais manipulação de dados para usar os resultados da consulta. Para obter mais informações, consulte Recuperar dados com consultas utilizando assemblies SDK.

Atribuir

Para entidades de propriedade da equipe ou do usuário, você atribui um registro a um novo proprietário. Para obter mais informações, consulte Propriedade da entidade. Para realizar esta ação, o chamador deve ter Assign message privileges e direitos de acesso nos registros de entidade.

As regras em cascata determinam se os registros relacionados serão atribuídos para outro usuário ao mesmo tempo. Para obter mais informações, consulte Comportamento do relacionamento entre entidades.

Quando um registro é atribuído a outro usuário ou equipe, o proprietário anterior ainda terá acesso ao registro se o atributo ShareToPreviousOwnerOnAssign for definido para true. Entretanto, o proprietário anterior não terá mais a propriedade do registro.

Compartilhar

Para entidades de propriedade do usuário ou da equipe, você pode compartilhar um registro com outros usuários ou equipes. Para realizar esta ação, o chamador deve ter GrantAccess message privileges, ModifyAccess message privileges e RevokeAccess message privileges e direitos de acesso nos registros da entidade.

As regras em cascata determinam se os registros relacionados serão compartilhados ao mesmo tempo. Para obter mais informações, consulte Comportamento do relacionamento entre entidades

Compartilhar é a forma que os usuários do Microsoft Dynamics 365 podem permitir que outros usuários acessem informações do cliente quando necessário. Por exemplo, um vendedor pode decidir compartilhar uma oportunidade com outro vendedor de modo que seja possível acompanhar o andamento de uma venda importante.

Use o GrantAccessRequest para compartilhar um registro. Use o ModifyAccessRequest para alterar como um registro foi compartilhado. Use o RevokeAccessRequest para remover todo o compartilhamento do registro.

Um usuário deverá ter direitos de compartilhamento para compartilhar registros relacionados com o cliente, como contatos, contas, oportunidades, ocorrências e pedidos, com qualquer outro usuário no Microsoft Dynamics 365. Quando um registro é compartilhado, é possível especificar os direitos para conceder o registro compartilhado.

A lista a seguir descreve as regras para compartilhar registros:

• Qualquer pessoa com privilégio compartilhado em um registro pode compartilhar com outros usuários ou equipes.

• Qualquer pessoa com o privilégio compartilhado em um registro pode definir direitos de acesso desse registro. Esses direitos de acesso controlam como um usuário compartilha um registro pode acessar o registro.

• Acesso em um registro compartilhado pode ser definido como todos os direitos de acesso, por exemplo, leitura ou gravação.

• Os direitos de acesso em um registro compartilhado podem ser diferentes para cada usuário que o registro foi compartilhado.

• Um registro pode ser compartilhado com a mesma entidade de segurança somente uma vez. Um usuário pode compartilhar um registro se possuem privilégios de compartilhamento nesse registro.

• Qualquer pessoa com o privilégio de compartilhamento em um registro de negócios pode alterar os direitos de acesso para usuários que possuem o registro compartilhado.

• Qualquer pessoa com o privilégio de compartilhamento em um registro de negócios pode remover o compartilhamento para um usuário especificado com o registro compartilhado.

• Qualquer pessoa com o privilégio de compartilhamento em um registro de negócios pode remover o compartilhamento para todos os usuários cujo registro foi compartilhado anteriormente.

Associar

Para realizar esta ação, o chamador deve ter Associate message privileges e direitos de acesso nos registros que sendo atualizados.

Associar cria várias associações em uma transação entre o registro especificado e cada registro no conjunto especificado para o relacionamento especificado.

Para um relacionamento um-para-muitos, este método define o ReferencingAttribute no registro relacionado a ID do registro especificado.

Para um relacionamento muito-para-muito, este método cria um registro na tabela de interseção do relacionamento, que contém a ID dos registros referenciados e de referência. O nome da tabela de interseção é definido na propriedade IntersectEntityName para o relacionamento.

Desassociar

Para realizar esta ação, o chamador deve ter Disassociate message privileges e direitos de acesso nos registros que sendo atualizados.

Desassociar reverte a operação de associação, atualizando os registros referenciados e de referência e excluindo o registro de interseção onde apropriado. Para obter mais informações, consulte Associar.

Definir Estado

Para realizar esta ação, o chamador deve ter SetState message privileges e direitos de acesso nos registros que sendo atualizados. A mensagem SetStateRequest atualiza os atributos StateCode e StatusCode do registro da entidade.

Propriedade da entidade

Há vários tipos diferentes de propriedade da entidade. A maioria das entidades, incluindo entidades personalizadas, são de propriedade da organização, do um usuário ou da equipe. Existem algumas entidades de negócios que não possuem um proprietário, como o tipo de desconto (lista de descontos), em que a propriedade é definida pelo desconto da entidade primária. O tipo de propriedade define algumas operações que podem ser executadas em um registro. A propriedade de uma entidade é definida na propriedade de metadados OwnershipType. A tabela a seguir lista as propriedades de propriedade.

Informações adicionais sobre a propriedade do usuário ou da equipe

Você pode usar a mensagem AssignRequest para alterar a propriedade de um registro. Para obter mais informações, consulte Atribuir. Você pode usar a mensagem ReassignObjectsOwnerRequest ou a mensagem ReassignObjectsSystemUserRequest para fazer a reatribuição em massa de todos os registros de um proprietário.

Estado e status do registro

A maioria das entidades corporativas têm duas propriedades para acompanhar o estado de um registro. São StateCode, que é chamado de Status no aplicativo Web e StatusCode, que é chamado de Razão do Status no aplicativo Web. Os valores de atributo StateCode e StatusCode são vinculados. O atributo StateCode é usado internamente para representar o status da entidade. O atributo StatusCode é usado para exibir este valor para o usuário final. O conjunto de códigos de estado válidos para uma entidade não é personalizável, mas os códigos de status são personalizáveis. Para a entidade ocorrência e entidades personalizadas, é possível definir critérios adicionais para transições válidas entre status. Para obter mais informações, consulte Personalizar metadados do atributo de entidades e Definir transições de modelo de estado personalizadas.

Imagens de entidade

Certas entidades do sistema incluem os atributos da imagem. É possível adicionar atributos de imagem para entidades personalizadas. Quando uma entidade tiver um atributo de imagem, você pode definir a propriedade PrimaryImageAttribute para controlar se a imagem será exibida no aplicativo. Quando a imagem é exibida nos usuários do aplicativo do aplicativo Web poderá carregar imagens para o registro da entidade. As seguintes entidades do sistema incluem atributos da imagem. Esses marcados com um asterisco são habilitados por padrão para mostrar no aplicativo.

Para obter mais informações:Atributos de data da imagem.

Confira Também

Entidades de administração e de segurança
Use metadados para gerar diagramas de entidades
Definir transições de modelo de estado personalizadas
Chave para diagramas de entidades
Modelar seus dados corporativos no Microsoft Dynamics 365
Personalizar metadados do relacionamento entre entidades
Comportamento do relacionamento entre entidades
Os metadados e os modelos de dados no Microsoft Dynamics 365
Usar o serviço da Organização com metadados do Dynamics 365
Embalar e distribuir extensões usando soluções
Entidades de serviço de organização
O modelo de segurança do Microsoft Dynamics 365
Exemplo: Definir e recuperar imagens de entidade
Amostra: Atribuir um registro a uma equipe
Exemplo: Compartilhar registros usando as mensagens GrantAccess, ModifyAccess e RevokeAccess
Amostra: Mesclar dois registros
Exemplo: Validar o estado do registro e definir o estado do registro
Exemplo: Acumular registros relacionados a um registro específico

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais