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.

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.

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.

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.

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.

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.

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:

• La Web API Function Reference enumera todas las funciones del sistema disponibles.

• El tema Web API Query Function Reference enumera las funciones que se proporcionan para usar como criterios en una consulta.

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