Tipos y operaciones de API web

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Para usar la API web necesita encontrar información sobre qué hay disponible para usar. El servicio se describe a través los documentos de servicio y de metadatos a los que puede obtener acceso. Este tema introducirá conceptos importantes y describirá cómo puede encontrar la información que necesita usando la documentación generada desde los documentos de servicio y de metadatos y la documentación de los tipos, funciones y acciones de entidad del sistema.

En este tema

Terminología

Documentos de servicio

Tipos de entidad

Propiedades

Propiedades de navegación

Acciones

Funciones

Tipos complejos

Tipos de enumeración

Terminología

La API web se implementa mediante el estándar OData v4 que usa un conjunto específico de términos con los que necesita estar familiarizado.Entity Data Model (EDM) es el modelo de datos abstracto que se usa para describir los datos expuestos por un servicio OData. La tabla siguiente es una lista de términos seleccionados definidos en OData Versión 4.0 Parte 1: Protocol Plus Errata 02 que debe comprender.

Término

Definición

Tipos de entidad

Tipo estructurados con nombre con una clave. Definen las propiedades y las relaciones con nombre de una entidad. Los tipos de entidad pueden obtenerse mediante herencia individual de otros tipos de entidad.

Entidades

Instancias de tipos de entidad (por ejemplo, account, opportunity).

Conjuntos de entidad

Colecciones con nombre de entidades (por ejemplo, accounts es un conjunto de entidades que contiene entidades account). Una clave de entidad identifica de manera única la entidad en un conjunto de entidades

Tipos complejos

Tipos estructurados con nombre sin clave que constan de un conjunto de propiedades. Los tipos complejos suelen utilizarse como valores de propiedad en entidades de modelo, o como parámetros o valores devueltos para operaciones.

Tipos de enumeración o tipos de Enum

Tipos primitivos con nombre cuyos valores son constantes con nombre con valores enteros subyacentes.

Funciones

Operaciones que no tienen efectos secundarios y pueden admitir creación adicional, por ejemplo, con operaciones adicionales de filtro, funciones o una acción

Acciones

Operaciones que permiten efectos secundarios, como modificación de datos y no se pueden crear aún más para evitar comportamiento no determinista

Documentos de servicio

Hay dos documentos de servicio a los que puede hacer referencia para obtener más información sobre la API web.

Documento de servicio

La consulta siguiente, escrita en el campo de dirección del explorador, devuelve el documento de servicio, una lista completa de todos los conjuntos de entidades que están disponibles para su organización. Tenga en cuenta que [URI de la organización] representa la dirección URL de la organización.


[URI de la organización]/api/data/v8.2

Los conjuntos de entidades se devuelven con el formato de una matriz JSON. Cada elemento de la matriz tiene tres propiedades que figuran en esta tabla.

Propiedad

Descripción

name

Este es el nombre del conjunto de entidades. Estos datos proceden de la propiedad EntityMetadata EntityType EntitySetName para la entidad.

kind

Para la API web únicamente se muestran conjuntos de entidades.

url

Este valor es el mismo que la propiedad name y representa la parte de la ruta de recursos para recuperar los datos de la entidad.

Esta información se puede recuperar mediante una solicitud GET y puede resultar útil para obtener una lista de todos los conjuntos de entidades disponibles mediante el servicio.

Documento de metadatos CSDL

Una solicitud GET al siguiente URL devolverá un documento Common Schema Definition Language (CSDL) bastante grande (más de 3,5 MB) o un documento de metadatos que describe los datos y las operaciones expuestos por el servicio.


[URI de la organización]/api/data/v8.2/$metadata

Este documento puede usarse como origen de datos para generar clases que proporcionarán objetos con establecimiento inflexible de tipos para el servicio. Pero si no está usando clases generadas, en su lugar puede revisar la documentación generada desde esta información. La Web API Reference utiliza información principalmente de este documento tomada de un sistema no personalizado.

Puede obtener más información sobre este documento en OData Version 4.0 Part 3: Common Schema Definition Language (CSDL) Plus Errata 02.

Sugerencia

Antes de leer el resto de este tema, descargue el CSDL para la organización y eche un vistazo a cómo se incluyen los tipos, las funciones, y las acciones descritos en el CSDL y la documentación de apoyo.

Tipos de entidad

La Web API EntityType Reference muestra cada uno de los tipos de entidades del sistema expuestos a través de la API web que almacena datos empresariales. Un tipo de entidad es un tipo estructurado con nombre con una clave. Define las propiedades y las relaciones con nombre de una entidad. Los tipos de entidad pueden obtenerse mediante herencia individual de otros tipos de entidad.Web API Metadata EntityType Reference enumera cada uno de los tipos de entidad usados para administrar metadatos del sistema. Ambos son tipos de entidad pero la manera de trabajar con ellos es diferente. Consulte Usar la API web con metadatos de Dynamics 365 para obtener información acerca de cómo usar entidades de modelo. Cada tipo de entidad se incluye en un elemento EntityType en el CSDL. A continuación se presenta la definición del account EntityType del CSDL con las propiedades y las propiedades de navegación quitadas.

<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 referencia de EntityType en la documentación del SDK usa información del CSDL o de metadatos para mostrar la siguiente información cuando está disponible.

Información

Descripción

Descripción

Una descripción de la entidad.

La información de la propiedad EntityMetadata EntityType Description se incluye en el elemento EntityType usando el elemento Annotation con el valor del atributo Term de Org.OData.Core.V1.Description.

Dirección URL de la colección

La dirección URL para obtener acceso a la colección de cada tipo.

La información de la propiedad EntityMetadata EntityType EntitySetName se incluye utilizando el elemento EntityContainer del CSDL. El atributo Name de cada elemento EntitySet controla cómo se accede a los datos mediante la dirección URL.

Tipo base

Éste es el tipo de entidad del que se hereda el tipo de entidad.

El atributo BaseType del elemento EntityType contiene el nombre del tipo de entidad. Este nombre se prefija con el alias del espacio de nombres de Microsoft.Dynamics.CRM: mscrm.Más información:Herencia de tipo

Nombre para mostrar

Esta información no se encuentra en el CSDL, se recupera de la propiedad EntityMetadata EntityType DisplayName.

Clave principal

El valor de propiedad que contiene el identificador único para referirse a una instancia de una entidad.

El valor de la propiedad EntityMetadata EntityType PrimaryIdAttribute se incluye en el elemento EntityType Key. Cada entidad puede tener solo una clave principal.

Las claves alternativas no se muestran aquí.Más información:Claves alternativas

Atributo principal

Muchas entidades requieren que se configure un valor de atributo principal, por lo que esto se incluye por comodidad.

Esta información no se encuentra en el CSDL, se recupera de la propiedad EntityMetadata EntityType PrimaryNameAttribute de metadatos.

Propiedades

Vea Propiedades.

Propiedades de navegación de un solo valor

Vea Propiedades de navegación de un solo valor.

Propiedades de navegación valoradas como colección

Vea Propiedades de navegación valoradas como colección.

Operaciones enlazadas al tipo de entidad

Cuando una operación está enlazada a un tipo de entidad específico, se muestra por comodidad.

Operaciones que utilizan el tipo de entidad

Esta lista muestra cualquier operación que pueda usar el tipo de entidad. Esto se obtiene recogiendo referencias a todas las operaciones que hagan referencia al tipo actual en los parámetros o como valor de devolución.

Tipos de entidad que se heredan del tipo de entidad.

Esta lista incluye cualquier tipo de entidad que se hereda directamente del tipo de entidad. Para obtener más información, vea Herencia de tipo.

Cambiar el nombre de un conjunto de entidades

De manera predeterminada, el nombre del conjunto de entidades coincide con el valor de la propiedad EntityMetadata EntityType LogicalCollectionName (EntityMetadataLogicalCollectionName). Si tiene una entidad personalizada a la que desea dirigirse con otro nombre de conjunto de entidades, puede actualizar el valor de propiedad EntityMetadata EntityType EntitySetName (EntityMetadata.EntitySetName) para usar otro nombre.

Claves alternativas

Aunque Microsoft Dynamics 365 permite crear claves alternativas, solo la clave principal se encontrará en la documentación de SDK de Microsoft Dynamics 365.

Ninguna de las entidades del sistema tienen claves alternativas definidas. Si define claves alternativas para una entidad, se incluirán en el elemento EntityType del CSDL como una Annotation como la siguiente:

<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>

La información sobre claves alternativas también se puede recuperar de los metadatos mediante la propiedad de navegación valorada como colección EntityMetadata EntityType Keys utilizando la API web o la propiedad EntityMetadata.Keys con el servicio de organización.

Herencia de tipo

La herencia permite compartir propiedades comunes y clasificar tipos de entidades en grupos. Todos los tipos de entidad de la API web se heredan de dos de los siguientes tipos de entidad. Todos los tipos de entidad de negocios se heredan del crmbaseentity EntityType y todas las entidades de modelo se heredan del crmmodelbaseentity EntityType.

Entidad base

Descripción

crmbaseentity EntityType

Todas las entidades de negocios se heredan de esta entidad. No tiene propiedades. Sirve solo como entidad base abstracta.

activitypointer EntityType

Todas las entidades de actividad se heredan de esta entidad. Define el conjunto común de propiedades y de propiedades de navegación para las entidades de actividad.

principal EntityType

El systemuser EntityType y el team EntityType heredan una propiedad ownerid común de esta entidad.

crmmodelbaseentity EntityType

Solo MetadataBase EntityType se hereda directamente desde esta entidad. No tiene propiedades. Sirve solo como entidad base abstracta.

MetadataBase EntityType

Todas las entidades de modelo se heredan de esta entidad. Proporciona las propiedades MetadataId y HasChanged modelo para todas las entidades de modelo.

AttributeMetadata EntityType

Todas las entidades de modelo que representan diferentes tipos de atributos se heredan de esta entidad.

EnumAttributeMetadata EntityType

Las entidades de modelo que representan atributos que incluyen un conjunto de opciones se heredan de esta entidad.

OptionSetMetadataBase EntityType

Este tipo de entidad de modelo proporciona un conjunto común de propiedades usadas por los tipos de entidad de modelo BooleanOptionSetMetadata EntityType y OptionSetMetadata EntityType que se heredan de él.

RelationshipMetadataBase EntityType

Este tipo de entidad proporciona un conjunto común de propiedades usadas por los tipos de entidad de modelo ManyToManyRelationshipMetadata EntityType y OneToManyRelationshipMetadata EntityType que se heredan de él.

Propiedades

Cada tipo de entidad puede tener propiedades declaradas que correspondan a atributos. En el contenido de Web API EntityType Reference y Web API Metadata EntityType Reference, las propiedades que se heredan de un tipo de entidad base se combinan en la lista de propiedades declaradas para cada tipo de entidad. La llamada a la herencia se realiza en la descripción para cada propiedad.

En los elementos EntityType del CSDL cada propiedad se incluye en un elemento Property con un valor de atributo de Name que corresponde a las propiedades que establecerá en código. El valor del atributo Type especifica el tipo de datos de la propiedad. Las propiedades de los tipos de entidad de negocios usan normalmente tipos primitivos OData.

El siguiente es un ejemplo de la propiedad account EntityType name definida en el CSDL.

<Property Name="name" Type="Edm.String" Unicode="false">
  <Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>

La descripción de la propiedad está disponible en un elemento Annotation con la propiedad del atributo Term de Org.OData.Core.V1.Description. Esta descripción se toma del valor de la propiedad AttributeMetadata EntityType Description. No todas las propiedades tienen una descripción.

Cada propiedad se puede calcular. Esto significa que el valor puede establecerlo el sistema. Esto se especifica en un elemento de Annotation con el valor de atributo Term de Org.OData.Core.V1.Computed.

Cada propiedad también pueden tener limitaciones sobre si se puede actualizar. Esto se define en un elemento Annotation con un valor de atributo Term de Org.OData.Core.V1.Permissions. El único conjunto de opciones para esto es Org.OData.Core.V1.PermissionType/Read, lo que indica que la propiedad es de solo lectura.

Tipos primitivos

OData admite una gran variedad de tipos de datos pero Microsoft Dynamics 365 no los usa todos. En la siguiente tabla se describe cómo se asignan los tipos de servicio de organización de Dynamics 365 a tipos primitivos OData.

Tipo de servicio de organización

Tipo de la API web

Descripción

BigInt

Edm.Int64

Entero de 64 bits firmado

Boolean

Edm.Booleano

Lógica de valor binario

CalendarRules

Propiedades de navegación de un solo valor

Propiedades de navegación de un solo valor específicas del calendarrule EntityType.

Cliente

Propiedades de navegación de un solo valor

El cliente de una entidad con este tipo de propiedad puede ser una propiedad de navegación de un solo valor establecida en un tipo de entidad account o contact mediante las respectivas propiedades de navegación de un solo valor. Cuando se establece una de las respectivas propiedades de la colección de un solo valor, se desactiva la otra.

DateTime

Edm.DateTimeOffset

Fecha y hora con desplazamiento de zona horaria, sin segundos intercalares
No hay tipo DateTime en OData.

Decimal

Edm.Decimal

Valores numéricos con precisión y escala fijas

Doble

Edm.Double

Número de coma flotante binaryIEEE 754 binary64 (15-17 dígitos decimales)

EntityName

Edm.String

Secuencia de caracteres UTF-8

Imagen

Edm.Binary

Datos binarios

Entero

Edm.Int32

Entero de 32 bits firmado

Búsqueda

Propiedad de navegación de un solo valor

Una referencia a una entidad específica

ManagedProperty

No disponible

Solo para uso interno.

Memorando

Edm.String

Secuencia de caracteres UTF-8

Dinero

Edm.Decimal

Valores numéricos con precisión y escala fijas

Propietario

Propiedad de navegación de un solo valor

Una referencia al principal EntityType. Los tipos de entidad systemuser y team heredan su propiedad ownerid del tipo de entidad prinicipal.

Lista de partes

Propiedad de navegación valorada como colección al tipo de entidad activityparty.

La propiedad activitypartyparticipationtypemask contiene un valor para representar el rol del participante. Para obtener más información, vea Tipos de grupo de actividad.

Los atributos de lista desplegable

Edm.Int32

Entero de 32 bits firmado

Estado

Edm.Int32

Entero de 32 bits firmado

Estado

Edm.Int32

Entero de 32 bits firmado

Cadena

Edm.String

Secuencia de caracteres UTF-8

Uniqueidentifier

Edm.Guid

Identificador único de 16 bytes (128 bits)

Propiedades de búsqueda

Para la mayoría de las propiedades de navegación de un solo valor encontrará una propiedad calculada de sólo lectura que use la convención de nomenclatura siguiente: _<name>_value donde <name> coincide con el nombre de la propiedad de navegación de un solo valor. La excepción a este patrón es cuando un atributo de búsqueda de la entidad puede aceptar varios tipos de referencias de entidad. Un ejemplo común es cómo el atributo customerid de la entidad incident se puede establecer en una referencia que sea una entidad contact o account. En las incident EntityTypeSingle-valued navigation properties encontrará customerid_account y customerid_contact como propiedades de navegación de un solo valor aparte para reflejar el cliente asociado a una oportunidad. Si establece una de estas propiedades de navegación de un solo valor, la otra se establecerá como nula porque ambas están enlazadas al atributo customerid. En las incident EntityTypeProperties encontrará una propiedad de búsqueda _customerid_value que contiene el mismo valor que está establecido para cualquiera de las propiedades de navegación de un solo valor que contenga un valor.

Generalmente, debe evitar el uso de propiedades de búsqueda y usar las propiedades de navegación de un solo valor correspondientes en su lugar. Estas propiedades se han incluido porque pueden ser útiles para determinados escenarios de integración. Estas propiedades son de solo lectura y calculadas porque simplemente reflejarán los cambios aplicados mediante la correspondiente propiedad de navegación de un solo valor.

Al incluir propiedades de búsqueda en una consulta, puede solicitar la inclusión de anotaciones que proporcionen más información sobre los datos que se establecen para estos atributos subyacentes que no están representados por una propiedad de navegación de un solo valor.Más información:Recuperar datos sobre propiedades de búsqueda

Propiedades de navegación

En OData, las propiedades de navegación le permiten tener acceso a datos relacionados con la entidad actual. Cuando recupera una entidad puede optar por expandir las propiedades de navegación para incluir los datos relacionados. Hay dos tipos de propiedades de navegación: de un solo valor y valoradas como colección.

Propiedades de navegación de un solo valor

Estas propiedades corresponden a atributos de búsqueda que admiten relaciones de varios a uno y permiten establecer una referencia a otra entidad. En el elemento CSDL EntityType, se definen como un elemento NavigationProperty con en el atributo Type establecido como un tipo único. El siguiente es un ejemplo de la propiedad de navegación de un solo valor account EntityType createdby en el CSDL.

<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
 <ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>

Cada propiedad de navegación que representa una propiedad de navegación de un solo valor tendrá su correspondiente propiedad de navegación valorada como colección indicada por el valor del atributo Partner. Cada propiedad de navegación de un solo valor también tiene un elemento ReferentialConstraint con el valor de atributo Property que representa la propiedad de búsqueda de sólo lectura calculada que puede usarse para recuperar el correspondiente valor GUID de la entidad relacionada.Más información:Propiedades de búsqueda

Propiedades de navegación valoradas como colección

Estas propiedades corresponden a relaciones de uno a varios o de varios a varios. En el elemento CSDL EntityType, se definen como un elemento NavigationProperty con en el atributo Type establecido como una colección de un tipo. Lo siguiente representa la propiedad de navegación valorada como colección de account EntityType Account_Tasks que representa una relación de uno a varios:

<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />

Cuando la propiedad de navegación valorada como colección representa una relación de varios a varios, el nombre de la propiedad de navegación y el nombre del asociado serán iguales. Lo siguiente representa la propiedad de navegación valorada como colección de account EntityType accountleads_association que representa una relación de varios a varios:

<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />

La diferencia entre relaciones de uno a varios y relaciones de varios a varios no es importante al usar la API web. La forma desasociar las entidades es la misma independientemente del tipo de relación. Aunque las relaciones de varios a varios siguen usando entidades de intersección en segundo plano, solo algunas entidades de intersección especiales del sistema se incluyen en la Web API EntityType Reference. Por ejemplo,campaignactivityitem EntityType es técnicamente una entidad de intersección, pero se incluye porque tiene más propiedades que una entidad de intersección ordinaria.

Un entidad de intersección ordinaria solo tiene las cuatro propiedades básicas requeridas para mantener la relación de varios a varios. Cuando crea una relación personalizada de varios a varios entre entidades, un entidad de intersección ordinario se creará para ayudar en la relación. Puesto que debe usar propiedades de navegación para realizar operaciones relacionadas con relaciones de varios a varios, las entidades de intersección ordinarias no se documentan pero continúan estando disponibles mediante la API web. Estos tipos de entidad de intersección son accesibles mediante un nombre establecido de entidad que use la convención de nomenclatura siguiente: <intersect entity logical name>+’collection’. Por ejemplo, puede recuperar información del tipo de entidad de intersección contactleads mediante [URI de la organización]/api/data/v8.2/contactleadscollection. Debe usar solo estas entidades de intersección ordinarias en situaciones donde desee aplicar seguimiento de cambios.

Acciones

Las acciones son operaciones que permiten efectos secundarios, como modificación de datos y no se pueden crear aún más para evitar comportamiento no determinista.

El tema Web API Action Reference enumera todas las acciones del sistema disponibles.Más información:Usar acciones de la API web.

Funciones

Las funciones son operaciones que no tienen efectos secundarios y pueden admitir creación adicional, por ejemplo, con operaciones adicionales de filtro, funciones o una acción

Existen dos tipos de funciones definidas en la API web:

Más información:Usar funciones de la API web

Tipos complejos

Los tipos complejos son tipos estructurados con nombre sin clave que constan de un conjunto de propiedades. Los tipos complejos suelen utilizarse como valores de propiedad en entidades de modelo, o como parámetros o valores devueltos para operaciones.

Web API ComplexType Reference incluye todos los tipos complejos del sistema. Los tipos complejos son tipos estructurados con nombre sin clave que constan de un conjunto de propiedades. Suelen utilizarse como valores de propiedad en entidades de modelo, o como parámetros o valores devueltos para operaciones. El siguiente es el WhoAmIResponse ComplexType del 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 enumeración

Los tipos de enumeración o EnumTypes son tipos primitivos con nombre cuyos valores son constantes con nombre con valores de entero subyacentes.

Web API EnumType Reference incluye todos los tipos de enumeración del sistema. Los tipos de enumeración son tipos primitivos con nombre cuyos valores son constantes con nombre con valores enteros subyacentes. El siguiente es el AccessRights EnumType del 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>

Ver también

Use la API web de Microsoft Dynamics 365
Autenticarse en Microsoft Dynamics 365 con la API web
Realizar operaciones mediante la API web

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright