Tipos de API da Web e operações
Publicado: janeiro de 2017
Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Para usar o API da Web você precisa localizar informações sobre o que está disponível para você usar. O serviço descreve documentos através do serviço e dos metadados que você pode acessar. Este tópico introduzirá conceitos e descreverá informações necessárias usando a documentação gerada dos documentos de serviço e dos metadados da documentação e os tipos de entidades do sistema e ações.
Neste tópico
Terminologia
Documentos de serviço
Tipos de Entidades
Propriedades
Propriedades de navegação
Ações
Functions
Tipos complexos
Tipos de Enumeração
Terminologia
API Web são implementados usando o padrão OData v4 que usa um conjunto específico de termos que você precisa conhecer.Entity Data Model (EDM) é o modelo de dados abstrato que é usado para descrever os dados expostos pelo serviço de OData. A tabela a seguir é uma lista selecionada de termos definida em OData Versão 4.0 Parte 1: Protocolo Mais Errata 02 que você deve compreender.
Termo |
Definição |
|---|---|
Tipos de Entidades |
Tipos estruturados de nome com uma chave. Definir as propriedades nomeadas de relacionamentos de uma entidade. Os tipos de entidade derivam de uma única herança de outros tipos de entidade. |
Entidades |
Remoção dos tipos de entidade (por exemplo, account, opportunity). |
Conjuntos de entidade |
Conjuntos nomeados de entidades (por exemplo accounts é uma entidade definida contendo entidades account). A chave identifica com exclusividade uma entidade na entidade de um conjunto de entidades |
Tipos complexos |
Tipos de dados Keyless nomeados consistem em um conjunto das propriedades. Tipos complexos são comumente usados como valores de propriedade em entidades modelo, ou como parâmetros ou valores em retorno para operações. |
Tipos da enumeração ou Tipos do enum |
Tipos primitivos cujos nomes são valores nomeados constantes com valores inteiros subjacentes. |
Functions |
Operações que não tem lados ruins e podem ser compatíveis com composição adicional, por exemplo, com operações de filtro adicionais, funções ou uma ação. |
Ações |
Operações que permitem efeitos ruins, como modificação de dados, e não podem ser compostas para evitar comportamento não determinado |
Documentos de serviço
Existem dois documentos que o serviço pode fazer referência para saber mais sobre como o API da Web.
Documento de serviço
A consulta a seguir, inserida para definir o campo de seu navegador, devolve o documento de serviço, uma lista completa de todas as entidades que estão disponíveis para sua organização. Observe que [organization URI] representa a URL da organização.
[URI da organização]/api/data/v8.2
Conjuntos de entidade são retornados no formato de uma matriz JSON. Matriz em cada item tem três como propriedades catalogadas nesta tabela.
Propriedade |
Descrição |
|---|---|
name |
Este é o nome do grupo de entidade. Esses dados são da propriedade EntityMetadata EntityTypeEntitySetName para a entidade. |
kind |
Para API da Web apenas grupos de entidade são listados. |
url |
Esse valor é o mesmo que a propriedade de name e isso representa a parte do caminho de recurso para tentar dados da entidade. |
Essas informações podem ser recuperadas usando uma solicitação que GET pode ser útil e obter uma lista de todos os conjuntos de usuários usando a entidade serviço.
Documento CSDL dos metadados
Uma solicitação de GET para o seguinte URL retornará um documento maior de Common Schema Definition Language (CSDL) (maior que 3,5 MB), ou documento de metadados que descreve os dados e operações expostos pelo serviço.
[URI da organização]/api/data/v8.2/$metadata
Este documento pode ser usado como fonte de dados para a gerar as classes que fornecerão objetos digitados para o serviço. Mas se não estiver usando classes geradas, talvez você queira revisar a documentação de informações gerada desta vez. O Web API Reference usa informações e executa esse documento do sistema não personalizado.
Você pode saber mais sobre esse documento em OData Versão 4.0 Parte 3: Schema Definition Language (CSDL) mais Errata 02.
Dica
Antes de ler o resto deste tópico, baixe o CSDL para sua empresa e dê uma olhada em como os tipos, funções e ações descritos são incluídos no CSDL e no documento de suporte.
Tipos de Entidades
O Web API EntityType Reference lista cada um dos tipos de entidades do sistema a API expostos da Web que armazenam dados corporativos. Um tipo de entidade é estruturado em um nome com uma chave. Define as propriedades nomeadas de relacionamentos de uma entidade. Os tipos de entidade derivam de uma única herança de outros tipos de entidade.Web API Metadata EntityType Reference lista cada um dos tipos de entidade usados para gerenciar os metadados do sistema. Há dois tipos de entidade, mas o modo como você trabalha com elas é diferente. Consulte Use o API da Web com metadados do Dynamics 365 para obter informações sobre usar entidades modelo. Cada tipo de entidade é incluído dentro de um elemento de EntityType no CSDL. A seguir a definição de account EntityType do CSDL com propriedades e propriedades de navegação removidas.
<EntityType Name="account" BaseType="mscrm.crmbaseentity">
<Key>
<PropertyRef Name="accountid" />
</Key>
<!--Properties and navigation properties removed for brevity-->
<Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>
Cada página de referência de EntityType no documento do SDK usa informações do CSDL ou metadados para exibir as informações a seguir quando disponível.
Informações |
Descrição |
|---|---|
Descrição |
Uma descrição da entidade. A informação de propriedade de EntityMetadata EntityType Description está incluída no elemento EntityType usando o elemento Annotation com o valor de atributo do Term de Org.OData.Core.V1.Description. |
Coleção URL |
Acessar a URL do conjunto de cada tipo. As informações de propriedade de EntityMetadata EntityType EntitySetName estão incluídas usando o elemento EntityContainer de CSDL. O atributo Name de cada elemento EntitySet controla como os dados são acessados por meio da URL. |
Tipo de base |
Este é o tipo de entidade que o tipo de entidade herda. O atributo de BaseType do elemento EntityType contém o nome do tipo de entidade. Esse nome é prefixado com o alias do Microsoft.Dynamics.CRM namespace: mscrm.Para obter mais informações:Herança de Tipo |
Nome para exibição |
Esta informação não está no CSDL, é recuperada da propriedade EntityMetadata EntityType DisplayName. |
Chave Primária |
Valor de propriedade que contém o identificador exclusivo para se referir a uma instância de uma entidade. O valor de propriedade de EntityMetadata EntityType PrimaryIdAttribute está incluído no elemento EntityType Key. Cada entidade pode ter apenas uma chave primária. As chaves alternativas a seguir não estão listadas.Para obter mais informações:Chaves alternativas |
Atributo Principal |
Muitas entidades exigem que um valor do atributo primário seja definido, incluído por conveniência. Esta informação não está no CSDL, é recuperada de metadados da propriedade EntityMetadata EntityType PrimaryNameAttribute. |
Propriedades |
Consulte Propriedades. |
Propriedades de navegação avaliadas uma vez |
Consulte Propriedades de navegação avaliadas uma vez. |
Propriedades de navegação avaliadas por coleção |
Consulte Propriedades de navegação avaliadas por coleção. |
Operações Bulk associadas ao tipo de entidade |
Quando uma operação é associada a um tipo de entidade em particular, listados por conveniência. |
Operações que usam o tipo de entidade |
Essa lista mostra todas as operações que possam usar o tipo de entidade. Isto é derivado da coleção de referências para todas as operações que referem-se ao tipo atual nos parâmetros ou como um valor de devolução. |
Tipos de entidade que herdam do tipo de entidade |
Essa lista inclui todos os tipos de entidade que herdaram diretamente de tipo de entidade. Consulte Herança de Tipo para obter mais informações. |
Alterar o nome de um conjunto de entidade
Por padrão, o nome de entidade do corresponde valor de propriedade EntityMetadata EntityTypeLogicalCollectionName(EntityMetadataLogicalCollectionName). Se você tiver personalizado uma entidade que você deseja resolver definido com um nome de entidade diferente, você poderá atualizar EntityMetadata EntityType EntitySetName (EntityMetadata. valor de propriedade deEntitySetName) para usar um nome diferente.
Chaves alternativas
Embora Microsoft Dynamics 365 permitir criar, simplesmente chaves alternativas a chave primária são encontradas na documentação SDK do Microsoft Dynamics 365 .
Nenhuma das entidades do sistema terão as teclas alternativas. Se você definir chaves alternativas para uma entidade, elas serão incluídas no elemento de CSDL EntityType como um Annotation a seguir:
<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
<Collection>
<Record Type="OData.Community.Keys.V1.AlternateKey">
<PropertyValue Property="Key">
<Collection>
<Record Type="OData.Community.Keys.V1.PropertyRef">
<PropertyValue Property="Alias" String="key name" />
<PropertyValue Property="Name" PropertyPath="key name" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
Informações sobre chaves alternativas também pode ser recuperada de metadados usando a propriedade de navegação de valor de coleção do EntityMetadata EntityType Keys usando o API da Web ou propriedade EntityMetadata.Keys usando o serviço de organização.
Herança de Tipo
O compartilhamento permite a herança de propriedades comum categorizando os tipos de entidade. Todos tipos de entidade na API da Web herdam de dois tipos de entidades a seguir. Todos tipos de entidade corporativa do crmbaseentity EntityType e todas as entidades de modelo herdam de crmmodelbaseentity EntityType.
Entidade base |
Descrição |
|---|---|
Todas as entidades de comércio herdam essa entidade. Não há nenhuma propriedade. Mostra apenas uma entidade abstrata base. |
|
Todas as entidades de atividade herdam essa entidade. Define o conjunto comum de propriedades e propriedade de navegação para entidades de atividade. |
|
O systemuser EntityType e team EntityType herdam uma propriedade comum ownerid desta entidade. |
|
Apenas MetadataBase EntityType herda diretamente desta entidade. Não há nenhuma propriedade. Mostra apenas uma entidade abstrata base. |
|
Todas as entidades modelo herdam essa entidade. Fornece MetadataId e HasChanged propriedades de todos modelos de entidade. |
|
Todas as entidades que representem modelo de diversos tipos herdam atributos da entidade. |
|
A modelagem da entidades que representam atributos contêm um conjunto que herdam essa entidade. |
|
Esse tipo de entidade de modelo fornece um conjunto comum de propriedades usadas por BooleanOptionSetMetadata EntityType e OptionSetMetadata EntityType tipos de entidade de modelo que herdam dele. |
|
Esse tipo de entidade de modelo fornece um conjunto comum de propriedades usadas por ManyToManyRelationshipMetadata EntityType e OneToManyRelationshipMetadata EntityType tipos de entidade de modelo que herdam dele. |
Propriedades
Cada tipo de entidade pode ter declarado as propriedades que correspondem aos atributos. No conteúdo Web API EntityType Reference e Web API Metadata EntityType Reference, as propriedades que são herdadas de um tipo de entidade base são combinados com a lista de propriedades declaradas de cada tipo de entidade. A herança é chamada em descrição para cada proprietário.
Elementos em cada EntityType propriedade são incluídos em um elemento Property com um valor de atributo correspondente Name das propriedades que definirão o código. O valor do atributo Type especifica o tipo de propriedade. Propriedades dos tipos de entidade de negócios usando tipos primitivos de OData.
Como exemplo, esta é a definição de account EntityType e name no CSDL.
<Property Name="name" Type="Edm.String" Unicode="false">
<Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>
A descrição da propriedade está disponível em um elemento de Annotationcom a propriedade de atributo Term de Org.OData.Core.V1.Description. A descrição é feita do valor de propriedade de AttributeMetadata EntityType Description. Tem todas propriedades tem uma descrição.
Cada propriedade pode ser computada. Isso significa que o valor pode ser definido pelo sistema. É especificado em Annotation elemento com o valor de atributo de Term de Org.OData.Core.V1.Computed.
Cada propriedade pode ter limitações na forma que é atualizada. É definido em um elemento de Annotation com um valor de atributo de Term de Org.OData.Core.V1.Permissions. O único conjunto de opções para esse Org.OData.Core.V1.PermissionType/Read, que indica que a propriedade é apenas leitura.
Tipos primitivos
O OData oferece suporte a uma ampla variedade de dados de tipos de Microsoft Dynamics 365, mas não usam todos. A tabela a seguir descreve como os tipos de serviços da organização Dynamics 365 são mapeados aos tipos primitivos OData .
Tipo de serviço da organização |
Tipo de API da Web |
Descrição |
|---|---|---|
BigInt |
Edm.Int64 |
Inteiro conectar ao de 64 bits |
Boolean |
Edm.Boolean |
Lógico de valor binário |
CalendarRules |
Propriedades de navegação avaliadas uma vez |
Propriedades de navegação de valor único específico de calendarrule EntityType. |
Cliente |
Propriedades de navegação avaliadas uma vez |
O cliente de uma entidade com esse tipo de propriedade pode ser uma propriedade de navegação de valor único definida para tipo de entidade de account or contact usando as propriedades de navegação de valor único respectivas. Quando uma única propriedade respectiva avaliada em conjunto é definida, está desmarcada para outra. |
DateTime |
Edm.DateTimeOffset |
Data e hora em um fuso horário de compensação, nenhum pulo de segundos |
Decimal |
Edm.Decimal |
Valores numéricos com precisão e escalas fixas |
Duplo |
Edm.Double |
Número de ponto flutuante IEEE 754 binary64 (dígitos decimais 15-17) |
EntityName |
Edm.String |
Sequência de caracteres UTF-8 |
Imagem |
Edm.Binary |
Dados binários |
Inteiro |
Edm.Int32 |
Inteiro conectar ao de 32 bits |
Pesquisa |
Propriedades de navegação avaliadas uma vez |
Uma referência a uma determinada entidade |
ManagedProperty |
Não aplicável |
Somente para uso interno. |
Memorando |
Edm.String |
Sequência de caracteres UTF-8 |
Dinheiro |
Edm.Decimal |
Valores numéricos com precisão e escalas fixas |
Proprietário |
Propriedades de navegação avaliadas uma vez |
Uma referência a principal EntityType. Os tipos systemuser entidade e de team herdam sua propriedade ownerid tipo de entidade prinicipal . |
Lista de participantes |
Propriedade de navegação de valor de coleção ao tipo de entidade de activityparty. |
A propriedade activitypartycontém um valor de participationtypemask para representar o participante. Consulte Tipos de participantes da atividade para obter mais informações. |
Atributos de lista de seleção |
Edm.Int32 |
Inteiro conectar ao de 32 bits |
Estado |
Edm.Int32 |
Inteiro conectar ao de 32 bits |
Status |
Edm.Int32 |
Inteiro conectar ao de 32 bits |
Cadeia de caracteres |
Edm.String |
Sequência de caracteres UTF-8 |
Uniqueidentifier |
Edm.Guid |
128 (16 bits) de byte exclusivo |
Procurar propriedades
Para a maioria das propriedades de navegação de valor único você encontrará uma propriedade apenas leitura que usa a convenção de nomes a seguir: _<name>_value onde o <name> combina o nome da propriedade de navegação de valor único. A exceção a isso é quando um atributo de pesquisa da entidade pode conter diversos tipos de referências de entidade. Um exemplo comum é que o atributo da entidade incidentcustomerid pode ser definido por uma referência a contact a entidade ou account .incident EntityTypeSingle-valued navigation properties você encontrará customerid_account propriedades e customerid_contact avaliado como único separadas de navegação para refletir o cliente associado a uma oportunidade. Se você definir umas das propriedades de navegação de valor único, a outra será definida como null porque elas estão vinculadas ao atributo customerid.incident EntityTypevocê encontraráProperties pesquisa da que contém _customerid_value o mesmo valor é definido para que nenhuma das propriedades de navegação avaliado única contém um valor.
Geralmente, é necessário impedir usar propriedades de pesquisa e as propriedades usadas avaliadas correspondendo a uma única navegação. Essas propriedades foram incluídas pois podem ser úteis para determinados cenários de integração. Essas propriedades são somente leitura e computadas porque elas refletirão as alterações aplicadas usando a propriedade de navegação de valor único correspondente.
Quando você inclui propriedades de busca em uma consulta, você pode solicitar anotações a serem incluídas que fornecem informações adicionais sobre os dados que são definidas sob atributos subjacentes que não são representados por uma propriedade de navegação de valor único.Para obter mais informações:Recuperar dados sobre as propriedades de pesquisa
Propriedades de navegação
Em OData, as propriedades de navegação permitem acessar dados relacionados a entidade atual. Quando você recupera uma entidade você pode escolher expandir as propriedades de navegação para incluir dados relacionados. Há dois tipos de propriedades de navegação: valor único e valor de coleção.
Propriedades de navegação avaliadas uma vez
Essas propriedades correspondem aos atributos de pesquisa que suportam os relacionamentos de muitos para um e permitem a configuração de uma referência a outra entidade. No elemento CSDL EntityType, eles são definidos como um elemento NavigationProperty com um atributo Type definido para um único tipo. Como exemplo, esta é a definição de account EntityType e createdby propriedade de navegação de valor único no CSDL:
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
<ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>
Cada propriedade de navegação que representa uma propriedade de navegação de valor único terá uma propriedade de navegação de valor de coleção correspondente indicado pelo valor de atributo de Partner. Cada propriedade de navegação de valor único tem um elemento ReferentialConstraint com valor de atributo Property que representa a propriedade de busca apenas leitura computada que pode ser usada para recuperar o valor de GUID correspondente da entidade relacionada.Para obter mais informações:Procurar propriedades
Propriedades de navegação avaliadas por coleção
As propriedades correspondem aos relacionamentos de um para muitos ou muitos para muitos. No elemento CSDL EntityType, eles são definidos como um elemento NavigationProperty com um atributo Type definido para a coleção de um tipo. A demonstração a seguir representa propriedade de navegação de valor de coleção account EntityType Account_Tasks que representa uma relação de um para muitos:
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
Quando a propriedade de navegação de valor de coleção representa uma relação muitos para muitos, o nome da propriedade de navegação e o nome do parceiro serão os mesmos. A demonstração a seguir representa propriedade de navegação de valor de coleção account EntityType accountleads_association que representa uma relação de muitos para muitos:
<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />
A diferença entre relacionamentos um para muitos e muitos para muitos não é importante ao usar o API da Web. O modo como você associa as entidades é o mesmo independentemente do tipo de relacionamento. Apesar das relações muitos para muitos ainda usarem entidades cruzadas atrás das cenas, apenas entidades cruzadas de sistema especial são incluídas dentro do Web API EntityType Reference. Por exemplo, campaignactivityitem EntityType é tecnicamente uma entidade cruzada, mas é incluída porque tem mais propriedades que uma entidade cruzada comum.
Uma entidade cruzada comum tem apenas quatro propriedades básicas necessárias para manter o relacionamento muitos para muitos. Quando você cria um relacionamento muitos para muitos entre entidades personalizadas, uma entidade cruzada será criada para suportar a relação. Como você precisa usar propriedades de navegação para executar operações que envolvam o relacionamento muitos para muitos, entidades cruzadas comuns não são documentadas mas ainda estão disponíveis usando o API da Web. Esses tipos de entidade cruzada são acessíveis usando m nome de entidade definido que usa a convenção de nomes a seguir: <nome çógico de entidade cruzada>+’coleção’. Por exemplo, você pode recuperar informações do tipo de entidade cruzada contactleads usando [URI da organização]/api/data/v8.2/contactleadscollection. Você só deverá usar essas entidades cruzadas comuns em situações onde deseja aplicar rastreamento.
Ações
Ações são operações que permitem efeitos ruins, como modificação de dados, e não podem ser compostas para evitar comportamento não determinado.
O tópico Web API Action Reference lista cada ação de sistema disponível.Para obter mais informações:Use ações API da Web.
Functions
Funções são operações que não tem lados ruins e podem ser compatíveis com composição adicional, por exemplo, com operações de filtro adicionais, funções ou uma ação.
Há dois tipos de funções definidas na API Web:
O Web API Function Reference lista cada função de sistema disponível.
O tópico Web API Query Function Reference lista funções que serão usadas como critérios em uma consulta.
Para obter mais informações:Usar funções da API Web
Tipos complexos
Tipos complexos são Keyless nomeados consistem em um conjunto das propriedades. Tipos complexos são comumente usados como valores de propriedade em entidades modelo, ou como parâmetros ou valores em retorno para operações.
Web API ComplexType Reference lista todos tipos complexos do sistema.Tipos complexos são Keyless nomeados consistem em um conjunto das propriedades. Eles são comumente usados como valores de propriedade em entidades modelo, ou como parâmetros ou valores em retorno para operações. Os itens a seguir de WhoAmIResponse ComplexType são de CSDL.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
Tipos de Enumeração
Tipos de enumeração ou EnumTypes são nomeados primitivos cujos nomes são valores nomeados constantes com valores inteiros subjacentes.
Web API EnumType Reference lista todos tipos enumerados do sistema.Tipos de enumeração são nomeados primitivos cujos nomes são valores nomeados constantes com valores inteiros subjacentes. Os itens a seguir de AccessRights EnumType são de CSDL.
<EnumType Name="AccessRights">
<Member Name="None" Value="0" />
<Member Name="ReadAccess" Value="1" />
<Member Name="WriteAccess" Value="2" />
<Member Name="AppendAccess" Value="4" />
<Member Name="AppendToAccess" Value="16" />
<Member Name="CreateAccess" Value="32" />
<Member Name="DeleteAccess" Value="65536" />
<Member Name="ShareAccess" Value="262144" />
<Member Name="AssignAccess" Value="524288" />
</EnumType>
Confira Também
Use a API da Web do Microsoft Dynamics 365
Autentique Microsoft Dynamics 365 com API da Web
Executar operações usando A API
Microsoft Dynamics 365
© 2017 Microsoft. Todos os direitos reservados. Direitos autorais