Partilhar via


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

crmbaseentity EntityType

Todas as entidades de comércio herdam essa entidade. Não há nenhuma propriedade. Mostra apenas uma entidade abstrata base.

activitypointer EntityType

Todas as entidades de atividade herdam essa entidade. Define o conjunto comum de propriedades e propriedade de navegação para entidades de atividade.

principal EntityType

O systemuser EntityType e team EntityType herdam uma propriedade comum ownerid desta entidade.

crmmodelbaseentity EntityType

Apenas MetadataBase EntityType herda diretamente desta entidade. Não há nenhuma propriedade. Mostra apenas uma entidade abstrata base.

MetadataBase EntityType

Todas as entidades modelo herdam essa entidade. Fornece MetadataId e HasChanged propriedades de todos modelos de entidade.

AttributeMetadata EntityType

Todas as entidades que representem modelo de diversos tipos herdam atributos da entidade.

EnumAttributeMetadata EntityType

A modelagem da entidades que representam atributos contêm um conjunto que herdam essa entidade.

OptionSetMetadataBase EntityType

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.

RelationshipMetadataBase EntityType

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
Não há tipo DateTime no OData.

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:

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