Metadados de entidadeEntity metadata

Cada entidade fornece a capacidade de armazenar dados estruturados.Each entity provides the capability to store structured data. Para programadores, as entidades correspondem às classes que irá utilizar ao trabalhar com dados no Common Data Service para Aplicações.For developers, entities correspond to the classes you will use when working with data in Common Data Service for Apps.

Nomes de entidadesEntity names

Cada entidade tem um nome exclusivo que é definido quando é criada.Each entity has a unique name defined when it is created. Este nome é apresentado de várias formas:This name is presented in several ways:

Propriedade de NomeName Property DescriçãoDescription
SchemaName Normalmente, é uma versão em maiúsculas do nome lógico.Typically, a Pascal cased version of the logical name. Por exemplo, Contai.e. Account
CollectionSchemaName Plural do nome do esquema.A plural form of the Schema name. Por exemplo, Contasi.e. Accounts
LogicalName Versão em minúsculas do nome do esquema.All lower-case version of the schema name. Por exemplo, contai.e. account
LogicalCollectionName Versão em minúsculas do nome do esquema de coleção.All lower-case version of the collection schema name. Por exemplo, contasi.e. accounts
EntitySetName Utilizado para identificar coleções com a API Web.Used to identify collections with the Web API. Por predefinição, é o mesmo que o nome de coleção lógico.By default, it is the same as the logical collection name.
É possível mudar o nome do Conjunto de Entidades ao atualizar os metadados através de forma programática.It is possible to change the Entity Set name by programmatically updating the metadata. No entanto, deve fazer isto antes de escrever qualquer código API Web para a entidade.But this should only be done before any Web API code is written for the entity. Mais informações: Guia do Programador do Dynamics 365 Customer Engagement: Operações e tipos de API Web > Alterar o nome de um conjunto de entidadesMore information: Dynamics 365 Customer Engagement Developer Guide: Web API types and operations > Change the name of an entity set

Nota

Quando criar uma entidade personalizada, o nome que escolher será anexado ao valor de prefixo de personalização do fabricante de soluções associado à solução em que a entidade foi criada.When you create a custom entity, the name you choose will be prepended with the customization prefix value of the solution publisher associated with the solution that the entity was created within. Além do nome do conjunto de entidade, não pode alterar os nomes de uma entidade após esta ser criada.Other than the entity set name, you cannot change the names of an entity after it is created. Se quiser nomes consistentes para os itens de metadados na sua solução, deve criá-los no contexto de uma solução que cria associada a um fabricante de soluções que contém o prefixo de personalização que pretende utilizar.If you want consistent names for metadata items in your solution, you should create them in the context of a solution you create associated with a solution publisher that contains the customization prefix you want to use. Mais informações: Criar um fabricante de soluções e uma soluçãoMore information : Create a solution publisher and solution

Cada entidade também tem três propriedades que podem apresentar valores localizados:Each entity also has three properties that can display localized values:

NomeName DescriçãoDescription
DisplayName Normalmente, é o mesmo que o nome de esquema, mas pode incluir espaços.Typically, the same as the schema name, but can include spaces. Por exemplo, Contai.e. Account
DisplayCollectionName Plural do nome a apresentar.A plural form of the Display name. Por exemplo, Contasi.e. Accounts
Description Uma frase curta que descreve a entidade, por exemplo, Empresas que representam um cliente ou potencial cliente. A empresa que é faturada em transações empresariais.A short sentence describing the entity i.e. Business that represents a customer or potential customer. The company that is billed in business transactions.

Estes são os valores localizáveis que são utilizados para fazer referência às entidades numa aplicação.These are the localizable values that are used to refer to the entities in an app. Estes valores podem ser alterados em qualquer altura.These values can be changed at any time. Para adicionar ou editar valores localizados, veja Guia de Personalização do Dynamics 365: Traduzir texto de campo e entidade personalizada para outros idiomas.To add or edit localized values see Dynamics 365 Customization Guide: Translate customized entity and field text into other languages.

Chave primáriaPrimary key

O valor da propriedade PrimaryIdAttribute é o nome lógico do atributo que é a chave primária da entidade.The PrimaryIdAttribute property value is the logical name of the attribute that is the primary key for the entity.

Por predefinição, todas as entidades têm um atributo de identificador exclusivo do GUID.By default, all entities have a single GUID unique identifier attribute. Normalmente, é denominado <nome lógico de entidade>+ Id.This is usually named < entity logical name >+ Id.

Nome principalPrimary name

O valor da propriedade PrimaryNameAttribute é o nome lógico do atributo que armazena o valor de cadeia que identifica o registo da entidade.The PrimaryNameAttribute property value is the logical name of the attribute that stores the string value that identifies the entity record. Este é o valor que será apresentado numa ligação para abrir o registo numa IU.This is the value that will be displayed in a link to open the record in a UI.

Exemplo: a entidade Contact utiliza o atributo fullname como o atributo de nome principal.Example: The Contact entity uses the fullname attribute as the primary name attribute.

Nota

Nem todas as entidades têm um nome principal.Not every entity will have a primary name. Algumas entidades não se destinam a ser apresentadas numa IU.Some entities are not intended to be displayed in a UI.

Imagens de entidadeEntity images

O valor da propriedade PrimaryImageAttribute é o nome lógico do atributo que armazena os dados de imagem do registo da entidade.The PrimaryImageAttribute property value is the logical name of the attribute that stores the image data for the entity record. Cada entidade só pode ter um atributo de imagem e o nome lógico desse atributo é sempre entityimage.Each entity can have only one image attribute and the logical name of that attribute is always entityimage.

Exemplo: o atributo Contact Entity EntityImage pode armazenar uma imagem do contacto.Example: The Contact Entity EntityImage attribute can store a picture of the contact.

Por motivos de desempenho, as imagens de entidade não estão incluídas em operações de obtenção a menos que seja pedido explicitamente.For performance reasons, entity images are not included in retrieve operations unless explicitly requested.

Cada entidade que suporta imagens de entidade terá três atributos de suporte.Each entity that supports entity images will have three supporting attributes.

SchemaNameSchemaName TipoType DescriçãoDescription
EntityImage_Timestamp BigIntType O valor representa quando a imagem foi atualizada pela última vez e é utilizado para ajudar a garantir que a última versão da imagem é transferida e colocada em cache no cliente.The value represents when the image was last updated and is used to help make sure that the latest version of the image is downloaded and cached on the client.
EntityImage_URL StringType Um URL absoluto para apresentar a imagem de entidade num cliente.An absolute URL to display the entity image in a client.
EntityImageId UniqueIdentifierType O identificador exclusivo da imagemThe unique identifier of the image

Mais informações:More information:

Nota

É diferente do ícone apresentado para uma entidade em aplicações baseadas em modelos.This is different from the icon displayed for an entity in model-driven apps. A propriedade IconVectorName contém o nome do recurso Web SVG que define isto.The IconVectorName property contains the name of the SVG web resource that sets this.

Tipos de entidadesTypes of entities

As capacidades e comportamento das entidades dependem de várias propriedades de entidade.The capabilities and behavior of entities depends on several entity properties. A maior parte destas propriedades é relativamente simples e tem nomes descritivos.Most of these properties are relatively simple and have descriptive names. As quatro entidades que exigem explicações adicionais são: Propriedade, Entidades de atividade, Entidade ActivityParty e Entidades subordinadas.Four that require some additional explanation are: Ownership, Activity entities, Activityparty entity and Child entities.

Propriedade de entidadeEntity ownership

As entidades podem ser categorizadas pela forma como os dados dentro das mesmas pertencem a alguém.Entities can be categorized by how the data within them is owned. Este é um conceito importante relacionado com a forma como a segurança é aplicada às entidades.This is an important concept related to how security is applied to entities. Esta informação está na propriedade OwnershipType.This information is in the OwnershipType property. A seguinte tabela descreve os diferentes tipos de propriedade:The following table describes the different ownership types:

Tipo de PropriedadeOwnership Type DescriçãoDescription
EmpresarialBusiness Os dados pertencem à Unidade de Negócio.Data belongs to the Business unit. O acesso aos dados pode ser controlado ao nível da unidade de negócio.Access to the data can be controlled at the business unit level.
NenhumNone Os dados não pertencem a outra entidade.Data not owned by another entity.
OrganizaçãoOrganization Os dados pertencem à organização.Data belongs to the organization. O acesso aos dados é controlado ao nível da organização.Access to the data is controlled at the organization level.
Utilizador ou EquipaUser or Team Os dados pertencem a um utilizador ou equipa.Data belongs to a user or a team. As ações que podem ser realizadas nestes registos podem ser controladas ao nível do utilizador.Actions that can be performed on these records can be controlled on a user level.

Quando cria novas entidades, as únicas opções de propriedade são: Organização ou Utilizador ou Equipa.When you create new entities, the only ownership options are: Organization or User or Team. Após escolher esta opção, não poderá alterá-la.Once you make a choice for this option, you cannot change it. Selecione Utilizador ou Equipa para obter um controlo mais detalhado sobre quem pode ver ou realizar ações nos registos.Choose User or Team for the most granular control over who can view or perform actions on the records. Selecione Organização quando este nível de controlo não for necessário.Choose Organization when this level of control is not necessary.

Entidades de atividadeActivity entities

Uma atividade é uma tarefa realizada, ou a ser realizada, por um utilizador.An activity is a task performed, or to be performed, by a user. Uma atividade é uma ação para a qual pode ser criada uma entrada num calendário.An activity is any action for which an entry can be made on a calendar.

As atividades são modeladas de forma diferente de outros tipos de entidades que armazenam dados empresariais.Activities are modeled differently from other kinds of entities that store business data. Os dados sobre atividades são apresentados frequentemente em conjunto numa lista, mas cada tipo de atividade necessita de propriedades exclusivas.Data about activities is frequently displayed together in a list, yet each kind of activity requires unique properties. Em vez de ter uma única entidade de atividade com todas as propriedades possíveis, existem tipos separados de entidades de atividade e cada uma herda propriedades de uma Entidade ActivityPointer base.Rather than have a single Activity entity with every possible property, there are separate kinds of activity entities and each of them inherits properties from a base ActivityPointer Entity. Estas entidades terão a propriedade IsActivity definida como verdadeira.These entities will have the IsActivity property set to true.

EntidadeEntity DescriçãoDescription
AppointmentAppointment O compromisso que representa um intervalo de tempo com horas de início/fim e duração.Commitment representing a time interval with start/end times and duration.
E-mailEmail A atividade que é entregue através de protocolos de e-mail.Activity that is delivered using email protocols.
FaxFax A atividade que controla o resultado da chamada e o número de páginas de um fax e opcionalmente armazena uma cópia eletrónica do documento.Activity that tracks call outcome and number of pages for a fax and optionally stores an electronic copy of the document.
LetraLetter A atividade que controla a entrega da carta.Activity that tracks the delivery of a letter. A atividade pode conter a cópia eletrónica da carta.The activity can contain the electronic copy of the letter.
PhoneCallPhoneCall A atividade para controlar uma chamada telefónica.Activity to track a telephone call.
RecurringAppointmentMasterRecurringAppointmentMaster O compromisso Principal de uma série de compromissos recorrentes.The Master appointment of a recurring appointment series.
SocialActivitySocialActivity Apenas para utilização interna.For internal use only.
TaskTask A atividade genérica que representa o trabalho que precisava de ser realizado.Generic activity representing work needed to be done.

Sempre que alguém criar um destes tipos de registos de entidade de atividade, será criado um registo de entidade ActivityPointer correspondente com o mesmo valor de atributo de identificador exclusivo ActivityId.Whenever anyone creates one of these kinds of activity entity records, a corresponding ActivityPointer entity record will be created with the same ActivityId unique identifier attribute value. Não pode criar, atualizar ou eliminar instâncias da entidade ActivityPointer, mas pode obtê-las.You cannot create, update, or delete instances of the ActivityPointer entity, but you can retrieve them. É isto que permite que todos os tipos de atividades sejam apresentados em conjunto numa lista.This is what allows all types of activities to be presented together in a list.

Pode criar entidades de atividades personalizadas que se comportam da mesma forma.You can create custom activity entities that behave the same way.

Entidade ActivityPartyActivityParty entity

Esta entidade é utilizada para adicionar estrutura a atributos PartyListType de entidade de atividade que incluem referências a outras entidades.This entity is used to add structure to activity entity PartyListType attributes that include references to other entities. Irá utilizar esta entidade ao definir valores para atributos de entidade de atividade, tal como Email.to ou PhoneCall.from.You will use this entity when setting values for activity entity attributes like Email.to or PhoneCall.from. Na entidade ActivityParty, pode configurar o atributo ParticipationTypeMask para definir a função que a referência está a desempenhar.Within the ActivityParty entity, you set the ParticipationTypeMask attribute to define the role that the reference is playing. As funções incluem Sender, ToRecipient, Organizer, entre outros.Roles include Sender, ToRecipient, Organizer and more.

Pode consultar a entidade ActivityParty, mas não pode criar, obter, atualizar ou eliminar uma entidade de atividade fora da atividade a que está relacionada.You can query the ActivityParty entity, but you cannot create, retrieve, update, or delete an activity party outside of the activity that it is related to. Mais informações:More information:

Entidades subordinadasChild entities

As entidades em que a propriedade IsChildEntity é verdadeira nunca terão privilégios definidos e nunca serão propriedade do Utilizador ou Equipa.Entities where the IsChildEntity property is true will never have any privileges defined and will never be User or Team owned. As operações que podem ser realizadas numa entidade subordinada estão vinculadas a uma entidade à qual estão associadas através de uma relação muitos para um.Operations that can be performed on a child entity are bound to an entity that they are associated to via a Many-to-one relationship. Os utilizadores só podem realizar operações em entidades subordinadas se conseguirem realizar a mesma operação na entidade relacionada.Users can only perform operations on child entities if they can perform the same operation on the related entity. As entidades subordinadas são eliminadas automaticamente quando o registo de entidade de que dependem é eliminado.Child entities get deleted automatically when the entity record they depend on is deleted.

Por exemplo, PostComment, PostLike e PostRole são subordinados da entidade Post.For example, PostComment, PostLike, and PostRole are each children of the Post entity.

Chaves de entidadeEntity keys

Cada definição de chave alternativa descreve um ou mais atributos em combinação que irá identificar exclusivamente uma instância de entidade.Each alternate key definition describes one or more attributes in combination that will uniquely identify an entity instance. Normalmente, as chaves alternativas só são aplicadas para integração com sistemas externos.Alternate keys are typically only applied for integration with external systems. Pode definir chaves alternativas para identificar exclusivamente um registo.You can define alternate keys to uniquely identify a record. Isto é útil se estiver a integrar dados com um sistema que não suporta chaves de identificador exclusivo do GUID.This is valuable if you are integrating data with a system that doesn’t support GUID unique identifier keys. Pode definir um único valor de campo ou combinação de valores de campo para identificar exclusivamente uma entidade.You can define a single field value or combination of field values to uniquely identify an entity. Adicionar uma chave alternativa irá impor uma restrição de exclusividade nestes atributos.Adding an alternate key will enforce a uniqueness constraint on these attributes. Não poderá criar ou atualizar outro registo de entidade para ter os mesmos valores.You will not be able to create or update another entity record to have the same values.

Mais informações:More information:

Estados de entidadeEntity states

A maior parte das entidades tem duas propriedades para controlar o estado de um registo.Most entities have two properties to track the state of a record. Estes são StateCode, que é denominado Estado em aplicações baseadas em modelos e StatusCode, que é denominado Razão do Estado em aplicações baseadas em modelos.These are StateCode, which is called Status in model-driven apps and StatusCode, which is called Status Reason in model-driven apps.

Ambos os atributos contêm um conjunto de opções que apresentam os valores válidos.Both attributes contain a set of options that display the valid values. Os valores de atributo StateCode e StatusCode estão ligados, por isso apenas determinadas opções StatusCode são válidas para um determinado StateCode.The StateCode and StatusCode attribute values are linked so that only certain StatusCode options are valid for a given StateCode.

Isto pode variar por entidade, mas o padrão comum para várias entidades e a predefinição para entidades personalizadas é:This can vary by entity but the common pattern for many entities, and the default for custom entities is this:

Opções StateCodeStateCode Options Opções StatusCodeStatusCode Options
0: Ativo0 : Active 1: Ativo1 : Active
1: Inativo1: Inactive 2: Inativo2: Inactive

Algumas atividades terão conjuntos de opções diferentes.Some entities will have different sets of options.

Exemplo: entidade PhoneCall, opções StateCode e StatusCodeExample: PhoneCall entity StateCode and StatusCode options

StateCode StatusCode
0: Aberto0 : Open 1: Aberto1: Open
1: Concluído1 : Completed 2: Efetuado2: Made
4: Recebido4: Received
2: Cancelado2: Cancelled 3: Cancelado3: Cancelled

O conjunto de códigos de estado válidos de uma entidade não é personalizável, mas os códigos de estado são personalizáveis.The set of valid state codes for an entity is not customizable, but the status codes are customizable. Pode adicionar outras opções de StatusCode para um StateCode correspondente.You can add additional StatusCode options for a corresponding StateCode.

Para entidades personalizadas, pode definir critérios adicionais para transições válidas entre estados.For custom entities, you can define additional criteria for valid transitions between statuses. Mais informações:More information:

Ver tambémSee also

Entidades do Common Data Service para AplicaçõesCommon Data Service for Apps entities