Recuperar una entidad usando API web

Publicado: enero de 2017

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

Use una solicitud GET para recuperar los datos para una entidad especificada como recurso con un identificador único. Para recuperar una entidad también puede solicitar propiedades específicas y expandir las propiedades de navegación para devolver propiedades de entidades relacionadas.

En este tema

Ejemplo de recuperación básica

Recuperar propiedades específicas

Recuperar con una clave alternativa

Recuperar un solo valor de propiedad

Recuperar valores de propiedad de navegación

Recuperar entidades relacionadas para una entidad ampliando las propiedades de navegación

Opciones para aplicar a entidades expandidas

Detectar si una entidad se ha modificado desde que se recuperó

Recuperar valores con formato

Ejemplo de recuperación básica

Este ejemplo devuelve datos de una instancia de entidad de cuenta con el valor de clave principal igual a 00000000-0000-0000-0000-000000000001.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)

Para recuperar más de una entidad a la vez, vea Ejemplo de consulta básica en el tema Consultar datos utilizando la API web.

Recuperar propiedades específicas

Use la opción de consulta del sistema $select para limitar las propiedades devueltas incluyendo una lista separada por comas de nombres de propiedad. Esta es una práctica recomendada importante de rendimiento. Si las propiedades no se especifican utilizando $select, todas las propiedades se devolverán.

El ejemplo siguiente recupera propiedades name y revenue para la entidad de cuenta con el valor de clave principal igual a 00000000-0000-0000-0000-000000000001

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name,revenue HTTP/1.1
  Accept: application/json
  Content-Type: application/json; charset=utf-8
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Respuesta

  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#accounts(name,revenue)/$entity",
  "@odata.etag": "W/\"502186\"",
  "name": "A. Datum Corporation (sample)",
  "revenue": 10000,
  "accountid": "00000000-0000-0000-0000-000000000001",
  "_transactioncurrencyid_value":"b2a6b689-9a39-e611-80d2-00155db44581"
  }
  

Al solicitar determinados tipos de propiedades puede esperar que las propiedades de solo lectura adicionales se devuelvan automáticamente.

Si solicita un valor monetario, se devolverá la propiedad de búsqueda _transactioncurrencyid_value. Esta propiedad solo contiene el valor GUID de la divisa de transacción para que pueda usar este valor para recuperar información acerca de la divisa con la transactioncurrency EntityType. De forma alternativa, al solicitar anotaciones también puede obtener más datos en la misma solicitud.Más información:Recuperar datos sobre propiedades de búsqueda

Si solicita una propiedad que forma parte de un atributo compuesto para una dirección, obtendrá además la propiedad compuesta. Por ejemplo, si la consulta solicita la propiedad address1_line1 para un contacto, se devolverá además la propiedad address1_composite.Más información:5bc03503-649d-42b5-a21f-e642c9923453#BKMK_CompositeAttributes.

Recuperar con una clave alternativa

Si una entidad tiene una clave alternativa definida, también puede usar la clave alternativa para recuperar la entidad en lugar del identificador único para la entidad. Por ejemplo, si la entidad Contact tiene una definición de clave alternativa que incluye las propiedades firstname y emailaddress1, puede recuperar el contacto mediante el uso de una consulta con los datos proporcionados para esas claves como se indica a continuación.

GET cc_WebAPI_ServiceURI/contacts(firstname='Joe',emailaddress1='abc@example.com')

En cualquier momento que necesite identificar de forma exclusiva una entidad para recuperar, actualizar o eliminar, puede usar las claves alternativas configuradas para la entidad. De forma predeterminada, no hay claves alternativas configuradas para entidades. Las claves alternativas sólo estarán disponibles si la organización las agrega.

Recuperar un solo valor de propiedad

Cuando solo necesita recuperar el valor de una sola propiedad de una entidad, se puede anexar el nombre de la propiedad a la URI para una entidad para devolver solo el valor de esa propiedad. Esto es una recomendación de rendimiento porque necesitan devolverse menos datos en la respuesta.

Este ejemplo sólo devuelve el valor de la propiedad de nombre de una entidad de cuenta.

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Respuesta

  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(00000000-0000-0000-0000-000000000001)/name",
  "value":"Adventure Works (sample)"
  }
  

Recuperar valores de propiedad de navegación

De la misma forma que puede recuperar valores de propiedad individuales, también puede obtener acceso a los valores de propiedades de navegación (campos de búsqueda) anexando el nombre de la propiedad de navegación a la URI que hace referencia a una entidad individual.

El siguiente ejemplo devuelve el nombre completo del contacto principal de una cuenta usando la propiedad de navegación de un solo valor primarycontactid.

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/primarycontactid?$select=fullname HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Respuesta

  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#contacts(fullname)/$entity",
  "@odata.etag": "W/\"500128\"",
  "fullname": "Rene Valdes (sample)",
  "contactid": "ff390c24-9c72-e511-80d4-00155d2a68d1"
  }
  

Para propiedades de navegación valoradas como colección tiene la opción de solicitar devolver solo referencias a las entidades relacionadas o simplemente un recuento de entidades relacionadas.

El siguiente ejemplo solo devolverá referencias a las tareas relacionadas con una cuenta específica agregando /$ref a la solicitud.

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/AccountTasks/$ref HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Respuesta

  HTTP/1.1 200 OK
  Content-Type: application/json; odata.metadata=minimal
  OData-Version: 4.0
  
  {
  "@odata.context": "cc_WebAPI_ServiceURI/$metadata#Collection($ref)",
  "value": [
  {
  "@odata.id": "cc_WebAPI_ServiceURI/tasks(6b5941dd-d175-e511-80d4-00155d2a68d1)"
  },
  {
  "@odata.id": "cc_WebAPI_ServiceURI/tasks(fcbb60ed-d175-e511-80d4-00155d2a68d1)"
  }
  ]
  }
  

El siguiente ejemplo devuelve el número de tareas relacionadas con una cuenta específica mediante la propiedad de navegación valorada como colección Account_Tasks con /$count anexado.

• Solicitud

  GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)/Account_Tasks/$count HTTP/1.1
  Accept: application/json
  OData-MaxVersion: 4.0
  OData-Version: 4.0
  

• Respuesta

  2
  

Recuperar entidades relacionadas para una entidad ampliando las propiedades de navegación

Use la opción de consulta del sistema $expand para controlar qué datos de entidades relacionadas se devuelven. Hay dos tipos de propiedades de navegación:

• Las propiedades de navegación de un solo valor corresponden a atributos de búsqueda que admiten relaciones de varios a uno y permiten establecer una referencia a otra entidad.

• Las propiedades de navegación valoradas como colección corresponden a relaciones de uno a varios o de varios a varios.

Si incluye simplemente el nombre de la propiedad de navegación, recibirá todas las propiedades de registros relacionados. Puede limitar las propiedades devueltas para registros relacionados con la opción de la consulta del sistema $select entre paréntesis después del nombre de propiedad de navegación. Use esta opción para las propiedades de navegación de un solo valor y valoradas como colección.

• Recupere entidades relacionadas para una instancia de entidad expandiendo las propiedades de navegación de un solo valor: El siguiente ejemplo demuestra cómo recuperar el contacto para una entidad de cuenta. Para el registro de contacto relacionado, solo recuperamos contactid y fullname.

  • Solicitud

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid($select=contactid,fullname) HTTP/1.1
    Accept: application/json
    OData-MaxVersion: 4.0
    OData-Version: 4.0
    

  • Respuesta

    HTTP/1.1 200 OK
    Content-Type: application/json; odata.metadata=minimal
    OData-Version: 4.0
    
    {
    "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid,primarycontactid(contactid,fullname))/$entity",
    "@odata.etag":"W/\"550616\"",
    "name":"Adventure Works (sample)",
    "accountid":"00000000-0000-0000-0000-000000000001",
    "primarycontactid":{
    "@odata.etag":"W/\"550626\"",
    "contactid":"c59648c3-68f7-e511-80d3-00155db53318",
    "fullname":"Nancy Anderson (sample)"
    }
    }
    

  En lugar de devolver entidades relacionadas para instancias de entidad, también puede devolver referencias (vínculos) a las entidades relacionadas expandiendo la propiedad de navegación de un solo valor con la opción $ref. El siguiente ejemplo devuelve vínculos al registro de contacto para la entidad de cuenta.

  • Solicitud

    GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$select=name&$expand=primarycontactid/$ref HTTP/1.1
    Accept: application/json
    OData-MaxVersion: 4.0
    OData-Version: 4.0
    

  • Respuesta

    HTTP/1.1 200 OK
    Content-Type: application/json; odata.metadata=minimal
    OData-Version: 4.0
    
    {
    "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name,primarycontactid)/$entity",
    "@odata.etag":"W/\"550616\"",
    "name":"Adventure Works (sample)",
    "accountid":"00000000-0000-0000-0000-000000000001",
    "_primarycontactid_value":"c59648c3-68f7-e511-80d3-00155db53318",
    "primarycontactid":{
    "@odata.id":"cc_WebAPI_ServiceURI/contacts(c59648c3-68f7-e511-80d3-00155db53318)"
    }
    }
    

  • Recupere entidades relacionadas para una instancia de entidad expandiendo las propiedades de navegación valoradas como colección: El siguiente ejemplo demuestra cómo puede recuperar todas las tareas asignadas a un registro de contacto.

    • Solicitud

      GET cc_WebAPI_ServiceURI/accounts(915e89f5-29fc-e511-80d2-00155db07c77)?$select=name&$expand=Account_Tasks($select=subject,scheduledstart)
      Accept: application/json
      OData-MaxVersion: 4.0
      OData-Version: 4.0
      

    • Respuesta

      HTTP/1.1 200 OK
      Content-Type: application/json; odata.metadata=minimal
      OData-Version: 4.0
      
      {
      "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(name,Account_Tasks,Account_Tasks(subject,scheduledstart))/$entity",
      "@odata.etag":"W/\"514069\"","name":"Sample Child Account 1","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
      "Account_Tasks":[
      {
      "@odata.etag":"W/\"514085\"",
      "subject":"Sample Task 1",
      "scheduledstart":"2016-04-11T15:00:00Z",
      "activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
      },{
      "@odata.etag":"W/\"514082\"",
      "subject":"Sample Task 2",
      "scheduledstart":"2016-04-13T15:00:00Z",
      "activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
      }
      ]
      }
      

    Nota

    Si expande parámetros de navegación valorados como colección para recuperar entidades relacionadas para conjuntos de entidades, una propiedad @odata.nextLink será devuelta en su lugar para las entidades relacionadas. Debe usar el valor de la propiedad @odata.nextLink con una nueva solicitud GET para devolver los datos requeridos.Más información:Recuperar entidades relacionadas ampliando las propiedades de navegación

• Recupere entidades relacionadas para una instancia de entidad expandiendo las propiedades de navegación de un solo valor y valoradas como colección: El siguiente ejemplo demuestra cómo puede expandir entidades relacionadas para una instancia de entidad utilizando propiedades de navegación de un solo valor y valoradas como colección.

  • Solicitud

    GET cc_WebAPI_ServiceURI/accounts(99390c24-9c72-e511-80d4-00155d2a68d1)?$select=accountid&$expand=parentaccountid($select%20=%20createdon,%20name),Account_Tasks($select%20=%20subject,%20scheduledstart) HTTP/1.1
    Accept: application/json
    Content-Type: application/json; charset=utf-8
    OData-MaxVersion: 4.0
    OData-Version: 4.0
    

  • Respuesta

    HTTP/1.1 200 OK
    Content-Type: application/json; odata.metadata=minimal
    OData-Version: 4.0
    
    {
    "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(accountid,parentaccountid,Account_Tasks,parentaccountid(createdon,name),Account_Tasks(subject,scheduledstart))/$entity","@odata.etag":"W/\"514069\"","accountid":"915e89f5-29fc-e511-80d2-00155db07c77",
    "parentaccountid":{
    "@odata.etag":"W/\"514074\"","createdon":"2016-04-06T00:29:04Z",
    "name":"Adventure Works (sample)",
    "accountid":"3adbf27c-8efb-e511-80d2-00155db07c77"
    },"Account_Tasks":[
    {
    "@odata.etag":"W/\"514085\"",
    "subject":"Sample Task 1",
    "scheduledstart":"2016-04-11T15:00:00Z",
    "activityid":"a983a612-3ffc-e511-80d2-00155db07c77"
    },{
    "@odata.etag":"W/\"514082\"",
    "subject":"Sample Task 2",
    "scheduledstart":"2016-04-13T15:00:00Z",
    "activityid":"7bcc572f-3ffc-e511-80d2-00155db07c77"
    }
    ]
    }
    

Opciones para aplicar a entidades expandidas

Puede aplicar algunas opciones de consulta del sistema a las entidades devueltas para una propiedad de navegación valorada como colección. Use una lista separada por punto y coma de opciones de consulta del sistema entre paréntesis después del nombre de la propiedad de navegación valorada como colección. Puede utilizar $select, $filter, $orderby y $top.

El siguiente ejemplo filtra los resultados de las entidades de tareas relacionadas con una cuenta a las que tienen un subject que termina con "1".

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($filter=endswith(subject,'1');$select=subject)

El siguiente ejemplo especifica que las tareas relacionadas deben devolverse en orden ascendente basándose en la propiedad createdon.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($orderby=createdon asc;$select=subject,createdon)

El siguiente ejemplo devuelve solamente la primera tarea relacionada.

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-0000-000000000001)?$expand=Account_Tasks($top=1;$select=subject)

Detectar si una entidad se ha modificado desde que se recuperó

Como recomendación de rendimiento solo debe solicitar los datos que necesite. Si ha recuperado anteriormente un registro de entidad, puede usar la ETag asociada a un registro anteriormente recuperado para realizar recuperaciones condicionales en dicho registro. Para obtener más información, vea Recuperaciones condicionales.

Recuperar valores con formato

La solicitud de valores con formato para recuperaciones de registros individuales se hace la misma forma que cuando se consultan conjuntos de entidades.Más información:Incluir valores con formato.

Ver también

Ejemplo de operaciones básicas de la API web (C#)
Ejemplo de operaciones básicas de la API web (JavaScript del lado del cliente)
Realizar operaciones mediante la API web
Componer solicitudes HTTP y administrar errores
Consultar datos utilizando la API web
Cree una entidad usando API web
Actualizar y eliminar entidades mediante la API web
Asociar y anular la asociación de entidades mediante la API web
Usar funciones de la API web
Usar acciones de la API web
Ejecute las operaciones por lotes mediante API web
Suplantar a otro usuario utilizando la API web
Realizar operaciones condicionales mediante la API web

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright